Update Contributing Docs (#1915)

* Update Contributing Docs
- Update docs with all new tox hotness
- Test running docs build:
  - `sphinx-build -a -b html -W docs/ docs/_build/`

Fixes #1907

* Fix docs/contributing_to_black.md lint

* Remove autogenerated copy pasta

* Fix review typos + regen automated docs via Running Sphinx v1.8.5

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index a4250f787185259a24eaa56b8e545d5d332b5922..571d870452bc4c6f36473d26026b5da83c915b95 100644 (file)
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -34,14 +34,40 @@ If you haven't used `pipenv` before but are comfortable with virtualenvs, just r
 `pip install pipenv` in the virtualenv you're already using and invoke the command above
 from the cloned _Black_ repo. It will do the correct thing.
 
-Before submitting pull requests, run lints and tests with:
+Non pipenv install works too:
 
 ```console
+$ pip install -r test_requirements
+$ pip install -e .[d]
+```
+
+Before submitting pull requests, run lints and tests with the following commands from
+the root of the black repo:
+
+```console
+# Linting
 $ pre-commit run -a
-$ python -m unittest
+
+# Unit tests
+$ tox -e py
+
+# Optional Fuzz testing
+$ tox -e fuzz
+
+# Optional CI run to test your changes on many popular python projects
 $ black-primer [-k -w /tmp/black_test_repos]
 ```
 
+### Docs Testing
+
+If you make changes to docs, you can test they still build locally too.
+
+```console
+$ pip install -r docs/requirements.txt
+$ pip install [-e] .[d]
+$ sphinx-build -a -b html -W docs/ docs/_build/
+```
+
 ## black-primer
 
 `black-primer` is used by CI to pull down well-known _Black_ formatted projects and see
@@ -52,7 +78,7 @@ your PR. You may need to change
 configuration for it to pass.
 
 For more `black-primer` information visit the
-[documentation](https://github.com/psf/black/blob/master/docs/black_primer.md#black-primer).
+[documentation](https://github.com/psf/black/blob/master/docs/black_primer.md).
 
 ## Hygiene
 

diff --git a/docs/change_log.md b/docs/change_log.md
index e6afefbf6864db875ff8ca8dd59ea75b17b8f8ca..066be76c06cbee5ee16c7b0dd73e8bfbb6cdb2ae 100644 (file)
--- a/docs/change_log.md
+++ b/docs/change_log.md
@@ -23,8 +23,15 @@
 
 - Added support for PEP 614 relaxed decorator syntax on python 3.9 (#1711)
 
-- Added `--stdin-filename` argument to allow stdin to respect `--force-exclude` rules.
-  Works very alike to flake8's `--stdin-display-name` (#1780)
+- Added parsing support for unparenthesized tuples and yield expressions in annotated
+  assignments (#1835)
+
+- use lowercase hex strings (#1692)
+
+#### _Packaging_
+
+- Self-contained native _Black_ binaries are now provided for releases via GitHub
+  Releases (#1743)
 
 ### 20.8b1
 

diff --git a/docs/contributing_to_black.md b/docs/contributing_to_black.md
index f0be872a578ccb885d4219c3c0d44965309b0cc4..562b43a76ac9b85a8cb6b9f5178f8b543c69c28e 100644 (file)
--- a/docs/contributing_to_black.md
+++ b/docs/contributing_to_black.md
@@ -36,14 +36,40 @@ If you haven't used `pipenv` before but are comfortable with virtualenvs, just r
 `pip install pipenv` in the virtualenv you're already using and invoke the command above
 from the cloned _Black_ repo. It will do the correct thing.
 
-Before submitting pull requests, run lints and tests with:
+Non pipenv install works too:
 
 ```console
+$ pip install -r test_requirements
+$ pip install -e .[d]
+```
+
+Before submitting pull requests, run lints and tests with the following commands from
+the root of the black repo:
+
+```console
+# Linting
 $ pre-commit run -a
-$ python -m unittest
+
+# Unit tests
+$ tox -e py
+
+# Optional Fuzz testing
+$ tox -e fuzz
+
+# Optional CI run to test your changes on many popular python projects
 $ black-primer [-k -w /tmp/black_test_repos]
 ```
 
+### Docs Testing
+
+If you make changes to docs, you can test they still build locally too.
+
+```console
+$ pip install -r docs/requirements.txt
+$ pip install [-e] .[d]
+$ sphinx-build -a -b html -W docs/ docs/_build/
+```
+
 ## black-primer
 
 `black-primer` is used by CI to pull down well-known _Black_ formatted projects and see
@@ -54,7 +80,7 @@ your PR. You may need to change
 configuration for it to pass.
 
 For more `black-primer` information visit the
-[documentation](https://github.com/psf/black/blob/master/docs/black_primer.md#).
+[documentation](https://github.com/psf/black/blob/master/docs/black_primer.md).
 
 ## Hygiene
 

diff --git a/docs/github_actions.md b/docs/github_actions.md
index ac80c2fab6f831688a88282fda221095e3c875ab..bd4680998d9304414c4b6741b942dd827db60f2e 100644 (file)
--- a/docs/github_actions.md
+++ b/docs/github_actions.md
@@ -15,7 +15,13 @@ jobs:
     steps:
       - uses: actions/checkout@v2
       - uses: actions/setup-python@v2
-      - uses: psf/black@stable # the default is equivalent to `black . --diff --check`.
-        with: # (optional - override the default parameters).
-          args: ". --diff --check"
+      - uses: psf/black@stable
+        with:
+          black_args: ". --check"
 ```
+
+## Inputs
+
+### `black_args`
+
+**optional**: Black input arguments. Defaults to `. --check --diff`.

diff --git a/docs/installation_and_usage.md b/docs/installation_and_usage.md
index c91a1c400efca787cc813ebd990e38e97e27eb8a..d0dd0c99dc5158dcaba4b37f914f20f02fa98575 100644 (file)
--- a/docs/installation_and_usage.md
+++ b/docs/installation_and_usage.md
@@ -90,6 +90,11 @@ Options:
                                   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.
@@ -119,7 +124,7 @@ about _Black_'s changes or will overwrite _Black_'s changes. A good example of t
 should be configured to neither warn about nor overwrite _Black_'s changes.
 
 Actual details on _Black_ compatible configurations for various tools can be found in
-[compatible_configs](https://github.com/psf/black/blob/master/docs/compatible_configs.md#).
+[compatible_configs](https://github.com/psf/black/blob/master/docs/compatible_configs.md#black-compatible-configurations).
 
 ## Migrating your code style without ruining git blame
 

diff --git a/docs/version_control_integration.md b/docs/version_control_integration.md
index 0e09854a2e5e1a8f194e508b6dd18c96630203fb..2d8bc172eba30dfad2311c1154fd077ffbd3ca83 100644 (file)
--- a/docs/version_control_integration.md
+++ b/docs/version_control_integration.md
@@ -23,11 +23,6 @@ for your project. See _Black_'s own
 [pyproject.toml](https://github.com/psf/black/blob/master/pyproject.toml) for an
 example.
 
-When using the `--diff` flag with `pre-commit`, you must also use the `--check` flag.
-When you want to run _Black_ only on specific files in pre-commit, either use
-pre-commit's own `files` and `exclude` or, when using _Black_'s `--include`, set
-`--force-exclude` to the negated regex of `--include`.
-
 If you're already using Python 3.7, switch the `language_version` accordingly. Finally,
 `stable` is a branch that tracks the latest release on PyPI. If you'd rather run on
 master, this is also an option.

diff --git a/test_requirements.txt b/test_requirements.txt
index 9f69b8edf83d899bcea2c092a3bbb932beee4e35..a1464e90686ce7a98ad1904b8eacc965d6783efa 100644 (file)
--- a/test_requirements.txt
+++ b/test_requirements.txt
@@ -1,5 +1,7 @@
+coverage >= 5.3
+pre-commit
 pytest >= 6.1.1
 pytest-mock >= 3.3.1
 pytest-cases >= 2.3.0
-coverage >= 5.3
 parameterized >= 0.7.4
+tox