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.

diff --git a/.github/workflows/doc.yml b/.github/workflows/doc.yml
index 930b6d440ff04fef065fd00cec2bc97f71146323..74ec316a7cfeb0e8e7db49e13103399d7c9e919c 100644 (file)
--- a/.github/workflows/doc.yml
+++ b/.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

diff --git a/readthedocs.yml b/.readthedocs.yaml
similarity index 55%
rename from readthedocs.yml
rename to .readthedocs.yaml
index 15065033d0f83a9068dfbe4388fe9a27d1b0da52..24eb3eaf6d9601a0072b2f4f4a5e308516692da3 100644 (file)
--- a/readthedocs.yml
+++ b/.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

diff --git a/Pipfile b/Pipfile
index d1842ff749ba5568e4ba582ffa463277c10b5473..b38595711378a3b26bd7d04cc2b9d47ac3a1aaba 100644 (file)
--- a/Pipfile
+++ b/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"

diff --git a/Pipfile.lock b/Pipfile.lock
index f973c8423e829f226c336617d658392e8cdab0aa..0b9e529e73b5a7a1e1c4c1345e40ef38edad9850 100644 (file)
--- a/Pipfile.lock
+++ b/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:832aa3cde19744e49938b91fea06d69ecb9e649c93ba974535d08ad92164f700"
+                "sha256:149e90d6d8ac20db7a955ad60cf0e6881a3f20d37096140088356da6c716b0b1",
+                "sha256:ef6aaac3ca6cd92904cdd0d83f629a15f18053ec84e6432106f7a4d04ae4f5fb"
             ],
-            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3'",
-            "version": "==20.3.0"
+            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3, 3.4'",
+            "version": "==21.2.0"
         },
         "black": {
             "editable": true,
@@ -290,13 +290,13 @@
         },
         "typing-extensions": {
             "hashes": [
-                "sha256:7cb407020f00f7bfc3cb3e7881628838e69d8f3fcab2f64742a5e76b2f841918",
-                "sha256:99d4073b617d30288f569d3f13d2bd7548c3a7e4c8de87db09a9d29bb3a4a60c",
-                "sha256:dafc7639cde7f1b6e1acc0f457842a83e722ccca8eef5270af2d74792619a89f"
+                "sha256:0ac0f89795dd19de6b97debb0c6af1c70987fd80a2d62d1958f7e56fcc31b497",
+                "sha256:50b6f157849174217d0656f99dc82fe932884fb250826c18350e159ec6cdf342",
+                "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:832aa3cde19744e49938b91fea06d69ecb9e649c93ba974535d08ad92164f700"
+                "sha256:149e90d6d8ac20db7a955ad60cf0e6881a3f20d37096140088356da6c716b0b1",
+                "sha256:ef6aaac3ca6cd92904cdd0d83f629a15f18053ec84e6432106f7a4d04ae4f5fb"
             ],
-            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3'",
-            "version": "==20.3.0"
+            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3, 3.4'",
+            "version": "==21.2.0"
         },
         "babel": {
             "hashes": [
@@ -631,11 +631,11 @@
         },
         "flake8": {
             "hashes": [
-                "sha256:1aa8990be1e689d96c745c5682b687ea49f2e05a443aff1f8251092b0014e378",
-                "sha256:3b9f848952dddccf635be78098ca75010f073bfe14d2c6bda867154bea728d2a"
+                "sha256:07528381786f2a6237b061f6e96610a4167b226cb926e2aa2b6b1d78057c576b",
+                "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:c3b9f995be0792cbbc8ab2f53d74072eb7ff8a8b622be8d61d38ab879709eca3"
+                "sha256:36be6bb3ad987bfdb839f5ba78ddf094552ca38ccbd784ae4f74a4e1419fc6e3",
+                "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:77fd75dad81109ee91f30eb49146196f79afbbae041f298ae4886c8c2b5e23d7"
+                "sha256:1833bf738e038e35d89cb3a07eb0d227ed647ce7dd357579b65343740c6d249c",
+                "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:e4bc99e43e19f70d22e528de8e7cce59f7e8e7c4c34dcba203de92de7a7c7c85"
+                "sha256:8d7db76e2f33cd1dc1fe0c76af9f09e5cf19ce2c2e85074bc82f272c0f7c08ce",
+                "sha256:fc262959a74cdc799d7fa9b30c320c17187485b9a1e8c39e988fc12f3adff63c"
             ],
             "index": "pypi",
-            "version": "==0.13.7"
+            "version": "==0.14.0"
         },
         "nodeenv": {
             "hashes": [
@@ -933,11 +933,11 @@
         },
         "pygments": {
             "hashes": [
-                "sha256:2656e1a6edcdabf4275f9a3640db59fd5de107d88e8663c5d4e9a0fa62f77f94",
-                "sha256:534ef71d539ae97d4c3a4cf7d6f110f214b0e687e92f9cb9d2a3b0d3101289c8"
+                "sha256:a18f47b506a429f6f4b9df81bb02beab9ca21d0a5fee38ed15aef65f0545519f",
+                "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:af9147e9aceda37c91a05f4deb128d4b4b49d6b199775fd2d2927768abdc8f50"
+                "sha256:270aaf10d87d0d4e095063c65bf3ddbc6ee3d0b226328ce21e036f946e421835",
+                "sha256:a86d6e1f5b1dc238b218b012df0aa79409667bb209e58da56d0b94704e712a97"
             ],
-            "version": "==1.4.0"
+            "version": "==1.5.0"
         },
         "secretstorage": {
             "hashes": [
@@ -1084,11 +1084,11 @@
         },
         "six": {
             "hashes": [
-                "sha256:30639c035cdb23534cd4aa2dd52c3bf48f06e5f4a941509c8bafd8ce11080259",
-                "sha256:8b74bedcbbbaca38ff6d7491d76f2b06b3592611af620f8426e82dddb04a5ced"
+                "sha256:1e61c37477a1626458e36f7b1d82aa5c9b094fa4802892072e49de9c60c4c926",
+                "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:99d4073b617d30288f569d3f13d2bd7548c3a7e4c8de87db09a9d29bb3a4a60c",
-                "sha256:dafc7639cde7f1b6e1acc0f457842a83e722ccca8eef5270af2d74792619a89f"
+                "sha256:0ac0f89795dd19de6b97debb0c6af1c70987fd80a2d62d1958f7e56fcc31b497",
+                "sha256:50b6f157849174217d0656f99dc82fe932884fb250826c18350e159ec6cdf342",
+                "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:a935126db63128861987a7d5d30e23e8ec045a73840eeccb467c148514e29535"
+                "sha256:307a555cf21e1550885c82120eccaf5acedf42978fd362d32ba8410f9593f543",
+                "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": [

diff --git a/docs/conf.py b/docs/conf.py
index d56737384525537a4c0edda56f8ef57bb30fb203..7162f13dd41c062088e105f50cafdd0b80575cb1 100644 (file)
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -59,6 +59,7 @@ extensions = [
     "sphinx.ext.intersphinx",
     "sphinx.ext.napoleon",
     "myst_parser",
+    "sphinxcontrib.programoutput",
 ]
 
 # If you need extensions of a certain version or higher, list them here.

diff --git a/docs/contributing/gauging_changes.md b/docs/contributing/gauging_changes.md
index 6b70e0bc9bc15dab0c680bd13a0257995d0445cc..b41c7a35dda06501c448e3d99db963438e1eb24a 100644 (file)
--- a/docs/contributing/gauging_changes.md
+++ b/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
-Usage: black-primer [OPTIONS]
+```{program-output} black-primer --help
 
-  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.
 ```

diff --git a/docs/requirements.txt b/docs/requirements.txt
index 6c34e1fefab4d45b72e1fb8dbc5404109071e433..c65cbe3c47621711865fe64357d18b8bd5a0da3c 100644 (file)
--- a/docs/requirements.txt
+++ b/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

diff --git a/docs/usage_and_configuration/black_as_a_server.md b/docs/usage_and_configuration/black_as_a_server.md
index 0c0382b3e50487650e625c3808b37da233dd954f..75a4d925a544397b7f445c6b6439d9ab8310890a 100644 (file)
--- a/docs/usage_and_configuration/black_as_a_server.md
+++ b/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
-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.
+```{program-output} blackd --help
+
 ```
 
 There is no official `blackd` client tool (yet!). You can test that blackd is working

diff --git a/docs/usage_and_configuration/the_basics.md b/docs/usage_and_configuration/the_basics.md
index 6fd8769b591bd0949f25c9614589c8552035a937..4ac1693ea8b273efe27f3a0bd61ce577cacacaee 100644 (file)
--- a/docs/usage_and_configuration/the_basics.md
+++ b/docs/usage_and_configuration/the_basics.md
@@ -34,92 +34,8 @@ running `black --help`.
 
 <summary>Help output</summary>
 
-```
-  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.
+```{program-output} black --help
+
 ```
 
 </details>