From: Richard Si <63936253+ichard26@users.noreply.github.com> Date: Mon, 10 May 2021 02:35:56 +0000 (-0400) Subject: Autogenerate black(d|-primer)? help in usage docs (#2212) X-Git-Url: https://git.madduck.net/etc/vim.git/commitdiff_plain/3d96b7f10a56fcf826693e98f08b673dad8ac256 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 930b6d4..74ec316 100644 --- 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 1506503..24eb3ea 100644 --- 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 d1842ff..b385957 100644 --- 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 f973c84..0b9e529 100644 --- 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 d567373..7162f13 100644 --- 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 6b70e0b..b41c7a3 100644 --- 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 6c34e1f..c65cbe3 100644 --- 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 0c0382b..75a4d92 100644 --- 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 6fd8769..4ac1693 100644 --- a/docs/usage_and_configuration/the_basics.md +++ b/docs/usage_and_configuration/the_basics.md @@ -34,92 +34,8 @@ running `black --help`. Help output -``` - 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 + ```