Switch out tox for nox

It's nicer to work with especially as it uses a bog standard Python file
for configuration. Its output is cleaner and it doesn't hide any magic
too.

Also the mypy cache has been reenabled since it speeds up pre-commit
hooks significantly which makes life easier :)

Hopefully this makes the initial set up process relatively painfree.

.github/workflows/doc.yml

@@ -25,9 +25,8 @@ jobs:
 
       - name: Install dependencies
         run: |
-          python -m pip install --upgrade pip setuptools wheel
-          python -m pip install -e ".[d]"
-          python -m pip install -r "docs/requirements.txt"
+          python -m pip install --upgrade pip
+          python -m pip install --upgrade nox
 
       - name: Build documentation
-        run: sphinx-build -a -b html -W --keep-going docs/ docs/_build
+        run: nox --force-color -s docs

.github/workflows/fuzz.yml

@@ -28,8 +28,7 @@ jobs:
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip
-          python -m pip install --upgrade tox
+          python -m pip install --upgrade nox
 
       - name: Run fuzz tests
-        run: |
-          tox -e fuzz
+        run: nox --force-color -s fuzz

.github/workflows/test.yml

@@ -26,6 +26,8 @@ jobs:
       matrix:
         python-version: ["3.6", "3.7", "3.8", "3.9", "3.10", "pypy-3.7"]
         os: [ubuntu-latest, macOS-latest, windows-latest]
+    env:
+      FORCE_COLOR: 1
 
     steps:
       - uses: actions/checkout@v2
@@ -38,17 +40,15 @@ jobs:
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip
-          python -m pip install --upgrade tox
+          python -m pip install --upgrade nox
 
       - name: Unit tests
         if: "!startsWith(matrix.python-version, 'pypy')"
-        run: |
-          tox -e ci-py -- -v --color=yes
+        run: nox -s tests-${{ matrix.python-version }} -- --no-xdist --verbose
 
-      - name: Unit tests pypy
+      - name: Unit tests (pypy)
         if: "startsWith(matrix.python-version, 'pypy')"
-        run: |
-          tox -e ci-pypy3 -- -v --color=yes
+        run: nox -s tests-pypy3 -- --no-xdist --verbose
 
       - name: Publish coverage to Coveralls
         # If pushed / is a pull request against main repo AND

.gitignore

@@ -1,26 +1,44 @@
-.venv
+# Testing, packaging, and documentation artifacts
 .coverage
 .coverage.*
-_build
-.DS_Store
-.vscode
-docs/_static/pypi.svg
-.tox
-__pycache__
-
-# Packaging artifacts
-black.egg-info
-black.dist-info
+docs/_build/
+docs/build/
 build/
 dist/
+black.egg-info
+black.dist-info/
 pip-wheel-metadata/
-.eggs
+.eggs/
+wheels/
 
-src/_black_version.py
-.idea
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
 
+# Virtual environments
+env
+venv
+.env
+.venv
+.nox
+.tox
+
+# Caches / temporary files
+.mypy_cache/
 .dmypy.json
 *.swp
 .hypothesis/
-venv/
 .ipynb_checkpoints/
+__pycache__/
+
+# Black autogenerated files
+docs/_static/pypi.svg
+src/_black_version.py
+
+# Personal developer files
+.vscode/
+.editorconfig
+.DS_Store
+.idea

docs/contributing/the_basics.md

@@ -7,65 +7,141 @@ An overview on contributing to the _Black_ project.
 Development on the latest version of Python is preferred. As of this writing it's 3.9.
 You can use any operating system.
 
-Install development dependencies inside a virtual environment of your choice, for
-example:
+Most development tasks are automated by [nox][nox] which automatically creates virtual
+environments and running the right commands. You'll most likely run the test suite,
+build docs, etc. using nox. Often, you can run `python -m pip install nox` to install
+and use it.
+
+```{tip}
+If you're on Linux or MacOS you might want to use [pipx][pipx] to install nox (and
+optionally pre-commit) to avoid interfering with the system Python installation.
+
+Alternatively install them into the virtual environment you'll be setting up below.
+```
+
+### Running black from source tree
+
+To run the `black` executable from your source tree during development, install _Black_
+locally using editable installation (inside a virtual environment). You can then invoke
+your local source tree _Black_ normally.
+
+**Linux / MacOS**
 
 ```console
 $ python3 -m venv .venv
 $ source .venv/bin/activate
-(.venv)$ pip install -r test_requirements.txt
-(.venv)$ pip install -e .[d]
-(.venv)$ pre-commit install
+(.venv)$ pip install -e .[d,jupyter]
 ```
 
-Before submitting pull requests, run lints and tests with the following commands from
-the root of the black repo:
+**Windows**
 
 ```console
-# Linting
-(.venv)$ pre-commit run -a
+$ py -m venv .venv
+$ .venv\Scripts\activate
+(.venv)$ python -m pip install -e .[d,jupyter]
+```
+
+### Running linters
 
-# Unit tests
-(.venv)$ tox -e py
+_Black_ uses [pre-commit][pre-commit] to manage linting. It has been configured with a
+list of _pre-commit hooks_ that each check a certain aspect of the codebase.
 
-# Optional Fuzz testing
-(.venv)$ tox -e fuzz
+```console
+$ nox -s lint
 ```
 
-### News / Changelog Requirement
+You can also setup pre-commit to automatically run before committing. First, install
+pre-commit similarly to nox and install the Git pre commit hook:
 
-`Black` has CI that will check for an entry corresponding to your PR in `CHANGES.md`. If
-you feel this PR does not require a changelog entry please state that in a comment and a
-maintainer can add a `skip news` label to make the CI pass. Otherwise, please ensure you
-have a line in the following format:
+```console
+$ python -m pip install pre-commit
+$ pre-commit install
+```
 
-```md
-- `Black` is now more awesome (#X)
+### Running tests
+
+Before opening a pull request that involves code, please run the test suite to verify
+the changes didn't break anything.
+
+```console
+$ nox -s tests-3.9
 ```
 
-Note that X should be your PR number, not issue number! To workout X, please use
-[Next PR Number](https://ichard26.github.io/next-pr-number/?owner=psf&name=black). This
-is not perfect but saves a lot of release overhead as now the releaser does not need to
-go back and workout what to add to the `CHANGES.md` for each release.
+The example above runs tests against Python 3.9. You can also use other versions like
+`3.7` and `pypy3`. If you don't specify a Python version, nox will look for Python
+installations for all the versions _Black_ supports and run the suite for each!
 
-### Style Changes
+By default, the test suite is ran with coverage and parallelization enabled, but you can
+disable them if they're causing you trouble:
+
+```console
+# to disable parallelization
+$ nox -s tests-3.9 -- --no-xdist
+# to disable coverage
+$ nox -s tests-3.9 -- --no-cov
+# to disable both
+$ nox -s tests-3.9 -- --no-cov --no-xdist
+```
+
+If you need to run the test suite manually, install the test dependencies in the virtual
+environment you've [previously set up](#running-black-from-source-tree) and then run
+pytest:
+
+**Linux / MacOS**
+
+```console
+(.venv)$ pip install -r tests/requirements.txt
+(.venv)$ pytest
+```
+
+**Windows**
+
+```console
+(.venv)$ python -m pip install -r tests\requirements.txt
+(.venv)$ pytest
+```
+
+### Building documentation
+
+If you make changes to docs, you can test they still build locally too.
+
+```console
+$ nox -s docs
+```
+
+If you are making many changes to docs, you may find it helpful to use the `docs-live`
+session. Each time you make a change to the docs they're rebuilt and the browser tab
+reloads.
+
+```console
+$ nox -s docs-live
+```
+
+## Style changes
 
 If a change would affect the advertised code style, please modify the documentation (The
 _Black_ code style) to reflect that change. Patches that fix unintended bugs in
 formatting don't need to be mentioned separately though. If the change is implemented
-with the `--preview` flag, please include the change in the future style document
-instead and write the changelog entry under a dedicated "Preview changes" heading.
+with the `--preview` flag, please include the change in
+{doc}`/the_black_code_style/future_style` instead and write the changelog entry under a
+dedicated "Preview changes" heading.
 
-### Docs Testing
+## Changelog requirement
 
-If you make changes to docs, you can test they still build locally too.
+_Black_ has CI that will check for an entry corresponding to your PR in `CHANGES.md`. If
+you feel this PR does not require a changelog entry please state that in a comment and a
+maintainer can add a `skip news` label to make the CI pass. Otherwise, please ensure you
+have a line in the following format:
 
-```console
-(.venv)$ pip install -r docs/requirements.txt
-(.venv)$ pip install [-e] .[d]
-(.venv)$ sphinx-build -a -b html -W docs/ docs/_build/
+```md
+- `Black` is now more awesome (#X)
 ```
 
+Note that X should be your PR number, not issue number! To workout X, please use
+[Next PR Number](https://ichard26.github.io/next-pr-number/?owner=psf&name=black). This
+is not perfect but saves a lot of release overhead as now the releaser does not need to
+go back and workout what to add to the `CHANGES.md` for each release.
+
 ## Hygiene
 
 If you're fixing a bug, add a test. Run it first to confirm it fails, then fix the bug,
@@ -77,4 +153,9 @@ any large feature, first open an issue for us to discuss the idea first.
 ## Finally
 
 Thanks again for your interest in improving the project! You're taking action when most
-people decide to sit and watch.
+people decide to sit and watch. If you ever need help feel free to ask on the relevant
+issue or chat with us in the [Python Discord server](https://discord.gg/RtVdv86PrH).
+
+[nox]: https://nox.thea.codes/en/stable/
+[pipx]: https://pypa.github.io/pipx/
+[pre-commit]: https://pre-commit.com/

mypy.ini

@@ -32,9 +32,6 @@ warn_unreachable=True
 disallow_untyped_defs=True
 check_untyped_defs=True
 
-# No incremental mode
-cache_dir=/dev/null
-
 [mypy-black]
 # The following is because of `patch_click()`. Remove when
 # we drop Python 3.6 support.