From 481aa764eb384fccfa2ddcf4be8c90854bf2028d Mon Sep 17 00:00:00 2001
From: Oliver Bestwalter <oliver@bestwalter.de>
Date: Fri, 21 Jun 2024 15:17:40 +0200
Subject: [PATCH] Merge pull request #12498 from
 webknjaz/maintenance/tox-descriptions

(cherry picked from commit b864e50138a34ebaf188829f2a4fcdf4d9e0a541)
---
 changelog/12498.contrib.rst |  5 +++++
 tox.ini                     | 27 +++++++++++++++++++++++++++
 2 files changed, 32 insertions(+)
 create mode 100644 changelog/12498.contrib.rst

diff --git a/changelog/12498.contrib.rst b/changelog/12498.contrib.rst
new file mode 100644
index 000000000..436c6f0e9
--- /dev/null
+++ b/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`
diff --git a/tox.ini b/tox.ini
index cd04d0c57..fe4dd8bcd 100644
--- a/tox.ini
+++ b/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)
@@ -156,6 +181,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