Document jupyter hook (#2416)

This also introduces a script so we can reference the latest version in
the example pre-commit configuration in the docs without forgetting to
update it when doing a release!

Commit history before merge:

* document jupyter hook
* note minimum version
* add check for pre-commit version
* use git tag
* curl api during ci
* parse version from changes file
* fixup script
* rename variables
* Tweak the docs & magical script
* fix couple of typos
* pin additional dependencies in hook
* Add types-PyYAML to lockfile

Co-authored-by: Richard Si <63936253+ichard26@users.noreply.github.com>

.pre-commit-config.yaml

@@ -12,6 +12,14 @@ repos:
         require_serial: true
         types_or: [python, pyi]
 
+      - id: check-pre-commit-rev-in-example
+        name: Check pre-commit rev in example
+        language: python
+        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"]
+
   - repo: https://gitlab.com/pycqa/flake8
     rev: 3.9.2
     hooks:
@@ -25,6 +33,7 @@ repos:
         exclude: ^docs/conf.py
         additional_dependencies:
           - types-dataclasses >= 0.1.3
+          - types-PyYAML
           - tomli >= 0.2.6, < 2.0.0
           - types-typed-ast >= 1.4.1
           - click >= 8.0.0

Pipfile

@@ -21,6 +21,7 @@ flake8-bugbear = "*"
 mypy = ">=0.910"
 types-dataclasses = ">=0.1.3"
 types-typed-ast = ">=1.4.1"
+types-PyYAML = ">=5.4.1"
 
 # Documentation related requirements.
 Sphinx = ">=4.1.2"

docs/faq.md

@@ -57,7 +57,7 @@ following will not be formatted:
   get_ipython().system('ls')
   ```
 
-- invalid syntax, as it can't be safely distinguished from automagics in the absense of
+- invalid syntax, as it can't be safely distinguished from automagics in the absence of
   a running `IPython` kernel.
 
 ## Why are Flake8's E203 and W503 violated?

docs/integrations/source_version_control.md

@@ -7,8 +7,21 @@ Use [pre-commit](https://pre-commit.com/). Once you
 ```yaml
 repos:
   - repo: https://github.com/psf/black
-    rev: stable # Replace by any tag/version: https://github.com/psf/black/tags
+    rev: 21.7b0
     hooks:
       - id: black
         language_version: python3 # Should be a command that runs python3.6+
 ```
+
+Feel free to switch out the `rev` value to something else, like another
+[tag/version][black-tags] or even a specific commit. Although we discourage the use of
+branches or other mutable refs since the hook [won't auto update as you may
+expect][pre-commit-mutable-rev].
+
+If you want support for Jupyter Notebooks as well, then replace `id: black` with
+`id: black-jupyter` (though note that it's only available from version `21.8b0`
+onwards).
+
+[black-tags]: https://github.com/psf/black/tags
+[pre-commit-mutable-rev]:
+  https://pre-commit.com/#using-the-latest-version-for-a-repository

scripts/check_pre_commit_rev_in_example.py

@@ -0,0 +1,54 @@
+"""
+Check that the rev value in the example pre-commit configuration matches
+the latest version of Black. This saves us from forgetting to update that
+during the release process.
+
+Why can't we just use `rev: stable` and call it a day? Well pre-commit
+won't auto update the hook as you may expect (and for good reasons, some
+technical and some pragmatic). Encouraging bad practice is also just
+not ideal. xref: https://github.com/psf/black/issues/420
+"""
+
+import os
+import sys
+
+import commonmark
+import yaml
+from bs4 import BeautifulSoup
+
+
+def main(changes: str, source_version_control: str) -> None:
+    changes_html = commonmark.commonmark(changes)
+    changes_soup = BeautifulSoup(changes_html, "html.parser")
+    headers = changes_soup.find_all("h2")
+    latest_tag, *_ = [
+        header.string for header in headers if header.string != "Unreleased"
+    ]
+
+    source_version_control_html = commonmark.commonmark(source_version_control)
+    source_version_control_soup = BeautifulSoup(
+        source_version_control_html, "html.parser"
+    )
+    pre_commit_repos = yaml.safe_load(
+        source_version_control_soup.find(class_="language-yaml").string
+    )["repos"]
+
+    for repo in pre_commit_repos:
+        pre_commit_rev = repo["rev"]
+        if not pre_commit_rev == latest_tag:
+            print(
+                "Please set the rev in ``source_version_control.md`` to be the latest "
+                f"one.\nExpected {latest_tag}, got {pre_commit_rev}.\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", "integrations", "source_version_control.md"),
+        encoding="utf-8",
+    ) as fd:
+        source_version_control = fd.read()
+    main(changes, source_version_control)

src/black/__init__.py

@@ -977,7 +977,7 @@ def format_ipynb_string(src_contents: str, *, fast: bool, mode: Mode) -> FileCon
     """Format Jupyter notebook.
 
     Operate cell-by-cell, only on code cells, only for Python notebooks.
-    If the ``.ipynb`` originally had a trailing newline, it'll be preseved.
+    If the ``.ipynb`` originally had a trailing newline, it'll be preserved.
     """
     trailing_newline = src_contents[-1] == "\n"
     modified = False