Merge pull request #12498 from webknjaz/maintenance/tox-descriptions

changelog/12498.contrib.rst

@@ -0,0 +1,5 @@
+All the undocumented ``tox`` environments now have descriptions.
+They can be listed in one's development environment by invoking
+``tox -av`` in a terminal.
+
+-- by :user:`webknjaz`

tox.ini

@@ -26,6 +26,20 @@ envlist =
 
 
 [testenv]
+description =
+    run the tests
+    coverage: collecting coverage
+    exceptiongroup: against `exceptiongroup`
+    nobyte: in no-bytecode mode
+    lsof: with `--lsof` pytest CLI option
+    numpy: against `numpy`
+    pexpect: against `pexpect`
+    pluggymain: against the bleeding edge `pluggy` from Git
+    pylib: against `py` lib
+    unittestextras: against the unit test extras
+    xdist: with pytest in parallel mode
+    under `{basepython}`
+    doctesting: including doctests
 commands =
     {env:_PYTEST_TOX_COVERAGE_RUN:} pytest {posargs:{env:_PYTEST_TOX_DEFAULT_POSARGS:}}
     doctesting: {env:_PYTEST_TOX_COVERAGE_RUN:} pytest --doctest-modules --pyargs _pytest
@@ -72,6 +86,8 @@ deps =
     {env:_PYTEST_TOX_EXTRA_DEP:}
 
 [testenv:linting]
+description =
+    run pre-commit-defined linters under `{basepython}`
 skip_install = True
 basepython = python3
 deps = pre-commit>=2.9.3
@@ -81,6 +97,9 @@ setenv =
     PYTHONWARNDEFAULTENCODING=
 
 [testenv:docs]
+description =
+    build the documentation site under \
+    `{toxinidir}{/}doc{/}en{/}_build{/}html` with `{basepython}`
 basepython = python3.12 # sync with rtd to get errors
 usedevelop = True
 deps =
@@ -102,6 +121,8 @@ setenv =
     PYTHONWARNDEFAULTENCODING=
 
 [testenv:docs-checklinks]
+description =
+    check the links in the documentation with `{basepython}`
 basepython = python3
 usedevelop = True
 changedir = doc/en
@@ -113,6 +134,8 @@ setenv =
     PYTHONWARNDEFAULTENCODING=
 
 [testenv:regen]
+description =
+    regenerate documentation examples under `{basepython}`
 changedir = doc/en
 basepython = python3
 passenv =
@@ -130,6 +153,8 @@ setenv =
     PYTHONWARNDEFAULTENCODING=
 
 [testenv:plugins]
+description =
+    run reverse dependency testing against pytest plugins under `{basepython}`
 # use latest versions of all plugins, including pre-releases
 pip_pre=true
 # use latest pip to get new dependency resolver (#7783)
@@ -154,6 +179,8 @@ commands =
     pytest simple_integration.py --force-sugar --flakes
 
 [testenv:py38-freeze]
+description =
+    test pytest frozen with `pyinstaller` under `{basepython}`
 changedir = testing/freeze
 deps =
     pyinstaller