Fix tox 4.0 support and docs

Also includes pre-commit autoupdate

.pre-commit-config.yaml

@@ -2,7 +2,7 @@ default_language_version:
     python: "3.10"
 repos:
 -   repo: https://github.com/psf/black
-    rev: 22.10.0
+    rev: 22.12.0
     hooks:
     -   id: black
         args: [--safe, --quiet]
@@ -44,7 +44,7 @@ repos:
     -   id: reorder-python-imports
         args: ['--application-directories=.:src', --py37-plus]
 -   repo: https://github.com/asottile/pyupgrade
-    rev: v3.3.0
+    rev: v3.3.1
     hooks:
     -   id: pyupgrade
         args: [--py37-plus]

.readthedocs.yml

@@ -2,9 +2,12 @@ version: 2
 
 python:
    install:
-      - requirements: doc/en/requirements.txt
+     # Install pytest first, then doc/en/requirements.txt.
+     # This order is important to honor any pins in doc/en/requirements.txt
+     # when the pinned library is also a dependency of pytest.
      - method: pip
        path: .
+     - requirements: doc/en/requirements.txt
 
 build:
   os: ubuntu-20.04

doc/en/explanation/goodpractices.rst

@@ -270,8 +270,8 @@ tox
 
 Once you are done with your work and want to make sure that your actual
 package passes all tests you may want to look into :doc:`tox <tox:index>`, the
-virtualenv test automation tool and its :doc:`pytest support <tox:example/pytest>`.
+virtualenv test automation tool.
-tox helps you to setup virtualenv environments with pre-defined
+``tox`` helps you to setup virtualenv environments with pre-defined
 dependencies and then executing a pre-configured test command with
 options.  It will run tests against the installed package and not
 against your source code checkout, helping to detect packaging

doc/en/requirements.txt

@@ -5,3 +5,7 @@ sphinx-removed-in>=0.2.0
 sphinx>=5,<6
 sphinxcontrib-trio
 sphinxcontrib-svg2pdfconverter
+# Pin packaging because it no longer handles 'latest' version, which
+# is the version that is assigned to the docs.
+# See https://github.com/pytest-dev/pytest/pull/10578#issuecomment-1348249045.
+packaging <22

tox.ini

@@ -30,7 +30,11 @@ commands =
     doctesting: {env:_PYTEST_TOX_COVERAGE_RUN:} pytest --doctest-modules --pyargs _pytest
     coverage: coverage combine
     coverage: coverage report -m
-passenv = USER USERNAME COVERAGE_* PYTEST_ADDOPTS TERM SETUPTOOLS_SCM_PRETEND_VERSION_FOR_PYTEST
+passenv =
+    COVERAGE_*
+    PYTEST_ADDOPTS
+    TERM
+    SETUPTOOLS_SCM_PRETEND_VERSION_FOR_PYTEST
 setenv =
     _PYTEST_TOX_DEFAULT_POSARGS={env:_PYTEST_TOX_POSARGS_DOCTESTING:} {env:_PYTEST_TOX_POSARGS_LSOF:} {env:_PYTEST_TOX_POSARGS_XDIST:}
 
@@ -93,7 +97,8 @@ commands =
 [testenv:regen]
 changedir = doc/en
 basepython = python3
-passenv = SETUPTOOLS_SCM_PRETEND_VERSION_FOR_PYTEST
+passenv =
+    SETUPTOOLS_SCM_PRETEND_VERSION_FOR_PYTEST
 deps =
     dataclasses
     PyYAML
@@ -161,7 +166,10 @@ commands = python scripts/prepare-release-pr.py {posargs}
 description = create GitHub release after deployment
 basepython = python3
 usedevelop = True
-passenv = GH_RELEASE_NOTES_TOKEN GITHUB_REF GITHUB_REPOSITORY
+passenv =
+    GH_RELEASE_NOTES_TOKEN
+    GITHUB_REF
+    GITHUB_REPOSITORY
 deps =
     github3.py
     pypandoc