From 4310f39bd94c7fa29fc31079247d2aab4bd50f1a Mon Sep 17 00:00:00 2001 From: Cooper Lees Date: Wed, 13 Jan 2021 15:17:30 -0800 Subject: [PATCH] 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 --- CONTRIBUTING.md | 32 ++++++++++++++++++++++++++--- docs/change_log.md | 11 ++++++++-- docs/contributing_to_black.md | 32 ++++++++++++++++++++++++++--- docs/github_actions.md | 12 ++++++++--- docs/installation_and_usage.md | 7 ++++++- docs/version_control_integration.md | 5 ----- test_requirements.txt | 4 +++- 7 files changed, 85 insertions(+), 18 deletions(-) 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 -- 2.39.5