From a69230ea5ff6d9f584713b2cf411bd0642debd87 Mon Sep 17 00:00:00 2001
From: Sviatoslav Sydorenko <wk@sydorenko.org.ua>
Date: Thu, 20 Jun 2024 16:51:50 +0200
Subject: [PATCH] =?UTF-8?q?=F0=9F=8E=A8=20Add=20descriptions=20to=20all=20?=
 =?UTF-8?q?`tox`=20environments?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Previously, a part of the environments weren't documented in the
config, making it difficult for the newbies to figure out what
their purposes are. This patch sets the descriptions for all the
envs listed with the `tox -av` command, leveraging the dynamic
factor-dependent explanation fragments.

```console
default environments:
linting                   -> run pre-commit-defined linters under `python3`
py38                      -> run the tests under `py38`
py39                      -> run the tests under `py39`
py310                     -> run the tests under `py310`
py311                     -> run the tests under `py311`
py312                     -> run the tests under `py312`
py313                     -> run the tests under `py313`
pypy3                     -> run the tests under `pypy3`
py38-pexpect              -> run the tests against `pexpect` under `py38`
py38-xdist                -> run the tests with pytest in parallel mode under `py38`
py38-unittestextras       -> run the tests against the unit test extras under `py38`
py38-numpy                -> run the tests against `numpy` under `py38`
py38-pluggymain           -> run the tests against the bleeding edge `pluggy` from Git under `py38`
py38-pylib                -> run the tests against `py` lib under `py38`
doctesting                -> run the tests under `~/.pyenv/versions/3.12.3/envs/pytest-pyenv-py3.12.3/bin/python` including doctests
doctesting-coverage       -> run the tests collecting coverage under `~/.pyenv/versions/3.12.3/envs/pytest-pyenv-py3.12.3/bin/python` including doctests
plugins                   -> run reverse dependency testing against pytest plugins under `~/.pyenv/versions/3.12.3/envs/pytest-pyenv-py3.12.3/bin/python`
py38-freeze               -> test pytest frozen with `pyinstaller` under `py38`
docs                      -> build the documentation site under `~/src/github/pytest-dev/pytest/doc/en/_build/html` with `python3`
docs-checklinks           -> check the links in the documentation with `python3`
py311-exceptiongroup      -> run the tests against `exceptiongroup` under `py311`

additional environments:
regen                     -> regenerate documentation examples under `python3`
release                   -> do a release, required posarg of the version number
prepare-release-pr        -> prepare a release PR from a manual trigger in GitHub actions
generate-gh-release-notes -> generate release notes that can be published as GitHub Release
nobyte                    -> run the tests in no-bytecode mode under `~/.pyenv/versions/3.12.3/envs/pytest-pyenv-py3.12.3/bin/python`
lsof                      -> run the tests with `--lsof` pytest CLI option under `~/.pyenv/versions/3.12.3/envs/pytest-pyenv-py3.12.3/bin/python`
```
---
 tox.ini | 27 +++++++++++++++++++++++++++
 1 file changed, 27 insertions(+)

diff --git a/tox.ini b/tox.ini
index ec74fc94b..61563ca2c 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)
@@ -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