Autogenerate black(d|-primer)? help in usage docs (#2212)

So these won't go out of date. This does mean the environment has be
setup a bit more carefully so the right version of the tool is used,
but thankfully the build environment is rebuilt on change on RTD anyway.

Also since the HTML docs are known to build fine, let's provide
downloadable HTMLzips of our docs.

This change needs RTD and GH to install Black with the [d] extra so
blackd's help can generated. While editing RTD's config file, let's
migrate the file to a non-deprecated filename.

Also I missed adding AUTHORS.md to the files key in the doc GHA config.

.github/workflows/doc.yml

@@ -7,12 +7,14 @@ on:
       - "README.md"
       - "CHANGES.md"
       - "CONTRIBUTING.md"
+      - "AUTHORS.md"
   pull_request:
     paths:
       - "docs/**"
       - "README.md"
       - "CHANGES.md"
       - "CONTRIBUTING.md"
+      - "AUTHORS.md"
 
 jobs:
   build:
@@ -35,8 +37,8 @@ jobs:
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip setuptools wheel
-          python -m pip install -e "."
+          python -m pip install -e ".[d]"
           python -m pip install -r "docs/requirements.txt"
 
       - name: Build documentation
-        run: sphinx-build -a -b html -W docs/ docs/_build/
+        run: sphinx-build -a -b html -W --keep-going docs/ docs/_build

.readthedocs.yaml

@@ -1,7 +1,14 @@
 version: 2
+
+formats:
+  - htmlzip
+
 python:
   version: 3.8
   install:
     - requirements: docs/requirements.txt
-    - method: setuptools
+
+    - method: pip
       path: .
+      extra_requirements:
+        - d

Pipfile

@@ -13,6 +13,7 @@ mypy = ">=0.812"
 pre-commit = "*"
 readme_renderer = "*"
 MyST-Parser = ">=0.13.7"
+sphinxcontrib-programoutput = ">=0.17"
 setuptools = ">=39.2.0"
 setuptools-scm = "*"
 twine = ">=1.11.0"

Pipfile.lock

@@ -1,7 +1,7 @@
 {
     "_meta": {
         "hash": {
-            "sha256": "62bc4bdb0117234d1f374b2dc0685369f6df7c7192d16409cc9c42a429770166"
+            "sha256": "fdfbacb362e4514e588736a7e8783837cb5e3aa2fbab98ea17894fdb50d51a8e"
         },
         "pipfile-spec": 6,
         "requires": {},
@@ -83,11 +83,11 @@
         },
         "attrs": {
             "hashes": [
-                "sha256:31b2eced602aa8423c2aea9c76a724617ed67cf9513173fd3a4f03e3a929c7e6",
+                "sha256:149e90d6d8ac20db7a955ad60cf0e6881a3f20d37096140088356da6c716b0b1",
-                "sha256:832aa3cde19744e49938b91fea06d69ecb9e649c93ba974535d08ad92164f700"
+                "sha256:ef6aaac3ca6cd92904cdd0d83f629a15f18053ec84e6432106f7a4d04ae4f5fb"
             ],
-            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3'",
+            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3, 3.4'",
-            "version": "==20.3.0"
+            "version": "==21.2.0"
         },
         "black": {
             "editable": true,
@@ -290,13 +290,13 @@
         },
         "typing-extensions": {
             "hashes": [
-                "sha256:7cb407020f00f7bfc3cb3e7881628838e69d8f3fcab2f64742a5e76b2f841918",
+                "sha256:0ac0f89795dd19de6b97debb0c6af1c70987fd80a2d62d1958f7e56fcc31b497",
-                "sha256:99d4073b617d30288f569d3f13d2bd7548c3a7e4c8de87db09a9d29bb3a4a60c",
+                "sha256:50b6f157849174217d0656f99dc82fe932884fb250826c18350e159ec6cdf342",
-                "sha256:dafc7639cde7f1b6e1acc0f457842a83e722ccca8eef5270af2d74792619a89f"
+                "sha256:779383f6086d90c99ae41cf0ff39aac8a7937a9283ce0a414e5dd782f4c94a84"
             ],
             "index": "pypi",
             "python_version <": "3.8",
-            "version": "==3.7.4.3",
+            "version": "==3.10.0.0",
             "version >=": "3.7.4"
         },
         "yarl": {
@@ -420,11 +420,11 @@
         },
         "attrs": {
             "hashes": [
-                "sha256:31b2eced602aa8423c2aea9c76a724617ed67cf9513173fd3a4f03e3a929c7e6",
+                "sha256:149e90d6d8ac20db7a955ad60cf0e6881a3f20d37096140088356da6c716b0b1",
-                "sha256:832aa3cde19744e49938b91fea06d69ecb9e649c93ba974535d08ad92164f700"
+                "sha256:ef6aaac3ca6cd92904cdd0d83f629a15f18053ec84e6432106f7a4d04ae4f5fb"
             ],
-            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3'",
+            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3, 3.4'",
-            "version": "==20.3.0"
+            "version": "==21.2.0"
         },
         "babel": {
             "hashes": [
@@ -631,11 +631,11 @@
         },
         "flake8": {
             "hashes": [
-                "sha256:1aa8990be1e689d96c745c5682b687ea49f2e05a443aff1f8251092b0014e378",
+                "sha256:07528381786f2a6237b061f6e96610a4167b226cb926e2aa2b6b1d78057c576b",
-                "sha256:3b9f848952dddccf635be78098ca75010f073bfe14d2c6bda867154bea728d2a"
+                "sha256:bf8fd333346d844f616e8d47905ef3a3384edae6b4e9beb0c5101e25e3110907"
             ],
             "index": "pypi",
-            "version": "==3.9.1"
+            "version": "==3.9.2"
         },
         "flake8-bugbear": {
             "hashes": [
@@ -703,11 +703,11 @@
         },
         "markdown-it-py": {
             "hashes": [
-                "sha256:30b3e9f8198dc82a5df0dcb73fd31d56cd9a43bf8a747feb10b2ba74f962bcb1",
+                "sha256:36be6bb3ad987bfdb839f5ba78ddf094552ca38ccbd784ae4f74a4e1419fc6e3",
-                "sha256:c3b9f995be0792cbbc8ab2f53d74072eb7ff8a8b622be8d61d38ab879709eca3"
+                "sha256:98080fc0bc34c4f2bcf0846a096a9429acbd9d5d8e67ed34026c03c61c464389"
             ],
             "markers": "python_version ~= '3.6'",
-            "version": "==0.6.2"
+            "version": "==1.1.0"
         },
         "markupsafe": {
             "hashes": [
@@ -776,11 +776,11 @@
         },
         "mdit-py-plugins": {
             "hashes": [
-                "sha256:1e467ca2ea056e8065cbd5d6c61e5052bb50826bde84c40f6a5ed77e82125710",
+                "sha256:1833bf738e038e35d89cb3a07eb0d227ed647ce7dd357579b65343740c6d249c",
-                "sha256:77fd75dad81109ee91f30eb49146196f79afbbae041f298ae4886c8c2b5e23d7"
+                "sha256:5991cef645502e80a5388ec4fc20885d2313d4871e8b8e320ca2de14ac0c015f"
             ],
             "markers": "python_version ~= '3.6'",
-            "version": "==0.2.6"
+            "version": "==0.2.8"
         },
         "multidict": {
             "hashes": [
@@ -863,11 +863,11 @@
         },
         "myst-parser": {
             "hashes": [
-                "sha256:260355b4da8e8865fe080b0638d7f1ab1791dc4bed02a7a48630b6bad4249219",
+                "sha256:8d7db76e2f33cd1dc1fe0c76af9f09e5cf19ce2c2e85074bc82f272c0f7c08ce",
-                "sha256:e4bc99e43e19f70d22e528de8e7cce59f7e8e7c4c34dcba203de92de7a7c7c85"
+                "sha256:fc262959a74cdc799d7fa9b30c320c17187485b9a1e8c39e988fc12f3adff63c"
             ],
             "index": "pypi",
-            "version": "==0.13.7"
+            "version": "==0.14.0"
         },
         "nodeenv": {
             "hashes": [
@@ -933,11 +933,11 @@
         },
         "pygments": {
             "hashes": [
-                "sha256:2656e1a6edcdabf4275f9a3640db59fd5de107d88e8663c5d4e9a0fa62f77f94",
+                "sha256:a18f47b506a429f6f4b9df81bb02beab9ca21d0a5fee38ed15aef65f0545519f",
-                "sha256:534ef71d539ae97d4c3a4cf7d6f110f214b0e687e92f9cb9d2a3b0d3101289c8"
+                "sha256:d66e804411278594d764fc69ec36ec13d9ae9147193a1740cd34d272ca383b8e"
             ],
             "markers": "python_version >= '3.5'",
-            "version": "==2.8.1"
+            "version": "==2.9.0"
         },
         "pyparsing": {
             "hashes": [
@@ -1061,10 +1061,10 @@
         },
         "rfc3986": {
             "hashes": [
-                "sha256:112398da31a3344dc25dbf477d8df6cb34f9278a94fee2625d89e4514be8bb9d",
+                "sha256:270aaf10d87d0d4e095063c65bf3ddbc6ee3d0b226328ce21e036f946e421835",
-                "sha256:af9147e9aceda37c91a05f4deb128d4b4b49d6b199775fd2d2927768abdc8f50"
+                "sha256:a86d6e1f5b1dc238b218b012df0aa79409667bb209e58da56d0b94704e712a97"
             ],
-            "version": "==1.4.0"
+            "version": "==1.5.0"
         },
         "secretstorage": {
             "hashes": [
@@ -1084,11 +1084,11 @@
         },
         "six": {
             "hashes": [
-                "sha256:30639c035cdb23534cd4aa2dd52c3bf48f06e5f4a941509c8bafd8ce11080259",
+                "sha256:1e61c37477a1626458e36f7b1d82aa5c9b094fa4802892072e49de9c60c4c926",
-                "sha256:8b74bedcbbbaca38ff6d7491d76f2b06b3592611af620f8426e82dddb04a5ced"
+                "sha256:8abb2f1d86890a2dfb989f9a77cfcfd3e47c2a354b01111771326f8aa26e0254"
             ],
             "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3'",
-            "version": "==1.15.0"
+            "version": "==1.16.0"
         },
         "snowballstemmer": {
             "hashes": [
@@ -1137,6 +1137,14 @@
             "markers": "python_version >= '3.5'",
             "version": "==1.0.1"
         },
+        "sphinxcontrib-programoutput": {
+            "hashes": [
+                "sha256:0ef1c1d9159dbe7103077748214305eb4e0138e861feb71c0c346afc5fe97f84",
+                "sha256:300ee9b8caee8355d25cc74b4d1c7efd12e608d2ad165e3141d31e6fbc152b7f"
+            ],
+            "index": "pypi",
+            "version": "==0.17"
+        },
         "sphinxcontrib-qthelp": {
             "hashes": [
                 "sha256:4c33767ee058b70dba89a6fc5c1892c0d57a54be67ddd3e7875a18d14cba5a72",
@@ -1215,13 +1223,13 @@
         },
         "typing-extensions": {
             "hashes": [
-                "sha256:7cb407020f00f7bfc3cb3e7881628838e69d8f3fcab2f64742a5e76b2f841918",
+                "sha256:0ac0f89795dd19de6b97debb0c6af1c70987fd80a2d62d1958f7e56fcc31b497",
-                "sha256:99d4073b617d30288f569d3f13d2bd7548c3a7e4c8de87db09a9d29bb3a4a60c",
+                "sha256:50b6f157849174217d0656f99dc82fe932884fb250826c18350e159ec6cdf342",
-                "sha256:dafc7639cde7f1b6e1acc0f457842a83e722ccca8eef5270af2d74792619a89f"
+                "sha256:779383f6086d90c99ae41cf0ff39aac8a7937a9283ce0a414e5dd782f4c94a84"
             ],
             "index": "pypi",
             "python_version <": "3.8",
-            "version": "==3.7.4.3",
+            "version": "==3.10.0.0",
             "version >=": "3.7.4"
         },
         "urllib3": {
@@ -1234,11 +1242,11 @@
         },
         "virtualenv": {
             "hashes": [
-                "sha256:09c61377ef072f43568207dc8e46ddeac6bcdcaf288d49011bda0e7f4d38c4a2",
+                "sha256:307a555cf21e1550885c82120eccaf5acedf42978fd362d32ba8410f9593f543",
-                "sha256:a935126db63128861987a7d5d30e23e8ec045a73840eeccb467c148514e29535"
+                "sha256:72cf267afc04bf9c86ec932329b7e94db6a0331ae9847576daaa7ca3c86b29a4"
             ],
             "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3'",
-            "version": "==20.4.4"
+            "version": "==20.4.6"
         },
         "webencodings": {
             "hashes": [

docs/conf.py

@@ -59,6 +59,7 @@ def make_pypi_svg(version: str) -> None:
     "sphinx.ext.intersphinx",
     "sphinx.ext.napoleon",
     "myst_parser",
+    "sphinxcontrib.programoutput",
 ]
 
 # If you need extensions of a certain version or higher, list them here.

docs/contributing/gauging_changes.md

@@ -37,25 +37,6 @@ If you're running locally yourself to test black on lots of code try:
 
 ### CLI arguments
 
-```text
+```{program-output} black-primer --help
-Usage: black-primer [OPTIONS]
 
-  primer - prime projects for blackening... 🏴
-
-Options:
-  -c, --config PATH      JSON config file path  [default: /Users/cooper/repos/
-                         black/src/black_primer/primer.json]
-
-  --debug                Turn on debug logging  [default: False]
-  -k, --keep             Keep workdir + repos post run  [default: False]
-  -L, --long-checkouts   Pull big projects to test  [default: False]
-  -R, --rebase           Rebase project if already checked out  [default:
-                         False]
-
-  -w, --workdir PATH     Directory path for repo checkouts  [default: /var/fol
-                         ders/tc/hbwxh76j1hn6gqjd2n2sjn4j9k1glp/T/primer.20200
-                         517125229]
-
-  -W, --workers INTEGER  Number of parallel worker coroutines  [default: 2]
-  -h, --help             Show this message and exit.
 ```

docs/requirements.txt

@@ -1,2 +1,3 @@
-MyST-Parser==0.13.7
+MyST-Parser==0.14.0
 Sphinx==3.5.4
+sphinxcontrib-programoutput==0.17

docs/usage_and_configuration/black_as_a_server.md

@@ -18,14 +18,8 @@ formatting requests.
 `blackd` provides even less options than _Black_. You can see them by running
 `blackd --help`:
 
-```text
+```{program-output} blackd --help
-Usage: blackd [OPTIONS]
 
-Options:
-  --bind-host TEXT                Address to bind the server to.
-  --bind-port INTEGER             Port to listen on
-  --version                       Show the version and exit.
-  -h, --help                      Show this message and exit.
 ```
 
 There is no official `blackd` client tool (yet!). You can test that blackd is working

docs/usage_and_configuration/the_basics.md

@@ -34,92 +34,8 @@ running `black --help`.
 
 <summary>Help output</summary>
 
-```
+```{program-output} black --help
-  Usage: black [OPTIONS] [SRC]...
 
-    The uncompromising code formatter.
-
-  Options:
-    -c, --code TEXT                 Format the code passed in as a string.
-    -l, --line-length INTEGER       How many characters per line to allow.
-                                    [default: 88]
-
-    -t, --target-version [py27|py33|py34|py35|py36|py37|py38|py39]
-                                    Python versions that should be supported by
-                                    Black's output. [default: per-file auto-
-                                    detection]
-
-    --pyi                           Format all input files like typing stubs
-                                    regardless of file extension (useful when
-                                    piping source on standard input).
-
-    -S, --skip-string-normalization
-                                    Don't normalize string quotes or prefixes.
-    -C, --skip-magic-trailing-comma
-                                    Don't use trailing commas as a reason to
-                                    split lines.
-
-    --check                         Don't write the files back, just return the
-                                    status. Return code 0 means nothing would
-                                    change. Return code 1 means some files
-                                    would be reformatted. Return code 123 means
-                                    there was an internal error.
-
-    --diff                          Don't write the files back, just output a
-                                    diff for each file on stdout.
-
-    --color / --no-color            Show colored diff. Only applies when
-                                    `--diff` is given.
-
-    --fast / --safe                 If --fast given, skip temporary sanity
-                                    checks. [default: --safe]
-
-    --include TEXT                  A regular expression that matches files and
-                                    directories that should be included on
-                                    recursive searches. An empty value means
-                                    all files are included regardless of the
-                                    name. Use forward slashes for directories
-                                    on all platforms (Windows, too). Exclusions
-                                    are calculated first, inclusions later.
-                                    [default: \.pyi?$]
-
-    --exclude TEXT                  A regular expression that matches files and
-                                    directories that should be excluded on
-                                    recursive searches. An empty value means no
-                                    paths are excluded. Use forward slashes for
-                                    directories on all platforms (Windows, too).
-                                    Exclusions are calculated first, inclusions
-                                    later.  [default: /(\.direnv|\.eggs|\.git|\.
-                                    hg|\.mypy_cache|\.nox|\.tox|\.venv|venv|\.svn|_bu
-                                    ild|buck-out|build|dist)/]
-
-    --extend-exclude TEXT           Like --exclude, but adds additional files
-                                    and directories on top of the excluded
-                                    ones (useful if you simply want to add to
-                                    the default).
-
-    --force-exclude TEXT            Like --exclude, but files and directories
-                                    matching this regex will be excluded even
-                                    when they are passed explicitly as
-                                    arguments.
-
-
-    --stdin-filename TEXT           The name of the file when passing it through
-                                    stdin. Useful to make sure Black will
-                                    respect --force-exclude option on some
-                                    editors that rely on using stdin.
-
-    -q, --quiet                     Don't emit non-error messages to stderr.
-                                    Errors are still emitted; silence those with
-                                    2>/dev/null.
-
-    -v, --verbose                   Also emit messages to stderr about files
-                                    that were not changed or were ignored due to
-                                    exclusion patterns.
-
-    --version                       Show the version and exit.
-    --config FILE                   Read configuration from FILE path.
-    -h, --help                      Show this message and exit.
 ```
 
 </details>