Unverified Commit 4310f39b authored by Cooper Lees's avatar Cooper Lees Committed by GitHub
Browse files

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
parent 3d068947
Loading
Loading
Loading
Loading
+29 −3
Changes for CONTRIBUTING.md: 29 added lines, 3 removed lines.
Original line number Diff line number Diff line
@@ -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

+9 −2
Changes for docs/change_log.md: 9 added lines, 2 removed lines.
Original line number Diff line number Diff line
@@ -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

+29 −3
Changes for docs/contributing_to_black.md: 29 added lines, 3 removed lines.
Original line number Diff line number Diff line
@@ -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

+9 −3
Changes for docs/github_actions.md: 9 added lines, 3 removed lines.
Original line number Diff line number Diff line
@@ -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`.
+6 −1
Changes for docs/installation_and_usage.md: 6 added lines, 1 removed line.
Original line number Diff line number Diff line
@@ -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

Loading