From: Cooper Lees <me@cooperlees.com>
Date: Wed, 13 Jan 2021 23:17:30 +0000 (-0800)
Subject: Update Contributing Docs (#1915)
X-Git-Url: https://git.madduck.net/etc/vim.git/commitdiff_plain/4310f39bd94c7fa29fc31079247d2aab4bd50f1a

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 a4250f7..571d870 100644
--- 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 e6afefb..066be76 100644
--- 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 f0be872..562b43a 100644
--- 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 ac80c2f..bd46809 100644
--- 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 c91a1c4..d0dd0c9 100644
--- 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 0e09854..2d8bc17 100644
--- 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 9f69b8e..a1464e9 100644
--- 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