document jupyter hook

[MarcoGorelli]

closes #420
addresses part of closes #2413

[JelleZijlstra]

We'll have to put something in the release process to update this (or better yet, make it automatic).

[MarcoGorelli]

sure, I'll add a pre-commit check for this

[MarcoGorelli]

I've added a check to ensure that the latest version from CHANGES.md matches the rev in the example from docs/integrations/source_version_control.md

Demo of me setting the wrong rev in the example, and pre-commit blocking the commit:

(venv) marcogorelli@OVMG025 black-dev % git diff                                       
diff --git a/docs/integrations/source_version_control.md b/docs/integrations/source_version_control.md
index b63a7c4..64cc8b1 100644
--- a/docs/integrations/source_version_control.md
+++ b/docs/integrations/source_version_control.md
@@ -7,7 +7,7 @@ Use [pre-commit](https://pre-commit.com/). Once you
 ```yaml
 repos:
   - repo: https://github.com/psf/black
-    rev: 21.7b0 # Replace by any tag/version: https://github.com/psf/black/tags
+    rev: 21.6b0 # Replace by any tag/version: https://github.com/psf/black/tags
     hooks:
       - id: black
         language_version: python3 # Should be a command that runs python3.6+
(venv) marcogorelli@OVMG025 black-dev % git commit -a -m 'foo'                         
black................................................(no files to check)Skipped
Check pre-commit rev in example is correct...............................Failed
- hook id: check-pre-commit-rev-in-example
- exit code: 1

Traceback (most recent call last):
  File "/usr/local/Cellar/python@3.9/3.9.6/Frameworks/Python.framework/Versions/3.9/lib/python3.9/runpy.py", line 197, in _run_module_as_main
    return _run_code(code, main_globals, None,
  File "/usr/local/Cellar/python@3.9/3.9.6/Frameworks/Python.framework/Versions/3.9/lib/python3.9/runpy.py", line 87, in _run_code
    exec(code, run_globals)
  File "/Users/marcogorelli/black-dev/scripts/check_pre_commit_rev_in_example.py", line 35, in <module>
    main(source_version_control)
  File "/Users/marcogorelli/black-dev/scripts/check_pre_commit_rev_in_example.py", line 23, in main
    raise ValueError(
ValueError: Please set the rev in ``source_version_control.md`` to be the latest one.
Expected 21.7b0, got 21.6b0

flake8...............................................(no files to check)Skipped
mypy.................................................(no files to check)Skipped
prettier.................................................................Passed
Fix End of Files.........................................................Passed
Trim Trailing Whitespace.................................................Passed

EDIT

updated example / traceback based on latest changes

[ichard26]

Awesome to see more automation come alive -- love it! Thank you!

[MarcoGorelli]

Thank you @ichard26 for adding an extra commit to fix it up, the corrections look good to me!

[ichard26]

Hmm, another idea I just thought of was to inject the value during the documentation build. This would further make it less likely we would miss this. OTOH it would be subject to bit-rot and could break (and we probably wouldn't notice until someone pointed it out to us). I don't really care either way since I pretty much always have pre-commit setup locally, but not everyone does (although we prep releases in PRs so the lint job should catch the issue before release so yeah).

[MarcoGorelli]

pre-commit runs in CI so I think this should be the fastest way to be averted if the rev hasn't been updated, and if you prep releases in PRs then all should be fine

happy to change if you prefer though

[ichard26]

I personally could go either way. Eventually this repo will probably get a custom local Sphinx extension where such a feature could be easily be added, but until then I don't think it's worth the complexity for this. I just brought that up as a potential suggestion someone else could've brought up for the sake of completeness.

[ichard26]

Since we want to do a release soon I'll merge. Jelle said that they don't really have time to review stuff right now so we can just iterate later.

[ichard26]

Thanks @MarcoGorelli for all of the awesome work, this included!

[MarcoGorelli]

Happy to contribute, thanks for your review! Please let me know when there's agreement on how to iterate on this