add check for version in the-basics example (#2459)

.pre-commit-config.yaml

@@ -18,7 +18,18 @@ repos:
         entry: python -m scripts.check_pre_commit_rev_in_example
         files: '(CHANGES\.md|source_version_control\.md)$'
         additional_dependencies:
-          ["commonmark==0.9.1", "pyyaml==5.4.1", "beautifulsoup4==4.9.3"]
+          &version_check_dependencies [
+            commonmark==0.9.1,
+            pyyaml==5.4.1,
+            beautifulsoup4==4.9.3,
+          ]
+
+      - id: check-version-in-the-basics-example
+        name: Check black version in the basics example
+        language: python
+        entry: python -m scripts.check_version_in_basics_example
+        files: '(CHANGES\.md|the_basics\.md)$'
+        additional_dependencies: *version_check_dependencies
 
   - repo: https://gitlab.com/pycqa/flake8
     rev: 3.9.2

scripts/check_version_in_basics_example.py

@@ -0,0 +1,47 @@
+"""
+Check that the rev value in the example from ``the_basics.md`` matches
+the latest version of Black. This saves us from forgetting to update that
+during the release process.
+"""
+
+import os
+import sys
+
+import commonmark
+from bs4 import BeautifulSoup
+
+
+def main(changes: str, the_basics: str) -> None:
+    changes_html = commonmark.commonmark(changes)
+    changes_soup = BeautifulSoup(changes_html, "html.parser")
+    headers = changes_soup.find_all("h2")
+    tags = [header.string for header in headers if header.string != "Unreleased"]
+    latest_tag = tags[0]
+
+    the_basics_html = commonmark.commonmark(the_basics)
+    the_basics_soup = BeautifulSoup(the_basics_html, "html.parser")
+    (version_example,) = [
+        code_block.string
+        for code_block in the_basics_soup.find_all(class_="language-console")
+        if "$ black --version" in code_block.string
+    ]
+
+    for tag in tags:
+        if tag in version_example and tag != latest_tag:
+            print(
+                "Please set the version in the ``black --version`` "
+                "example from ``the_basics.md`` to be the latest one.\n"
+                f"Expected {latest_tag}, got {tag}.\n"
+            )
+            sys.exit(1)
+
+
+if __name__ == "__main__":
+    with open("CHANGES.md", encoding="utf-8") as fd:
+        changes = fd.read()
+    with open(
+        os.path.join("docs", "usage_and_configuration", "the_basics.md"),
+        encoding="utf-8",
+    ) as fd:
+        the_basics = fd.read()
+    main(changes, the_basics)