doc: use `envvar` directive for environment variables (#6874)

This changes the link anchors in "reference.html", from e.g.
`reference.html#pytest-current-test` to
`reference.html#envvar-PYTEST_CURRENT_TEST`, but I think that is OK, and
not worth adding labels for the old anchors.

doc/en/example/simple.rst

@@ -910,9 +910,9 @@ information.
 
 Sometimes a test session might get stuck and there might be no easy way to figure out
 which test got stuck, for example if pytest was run in quiet mode (``-q``) or you don't have access to the console
-output. This is particularly a problem if the problem helps only sporadically, the famous "flaky" kind of tests.
+output. This is particularly a problem if the problem happens only sporadically, the famous "flaky" kind of tests.
 
-``pytest`` sets a ``PYTEST_CURRENT_TEST`` environment variable when running tests, which can be inspected
+``pytest`` sets the :envvar:`PYTEST_CURRENT_TEST` environment variable when running tests, which can be inspected
 by process monitoring utilities or libraries like `psutil <https://pypi.org/project/psutil/>`_ to discover which
 test got stuck if necessary:
 
@@ -926,8 +926,8 @@ test got stuck if necessary:
             print(f'pytest process {pid} running: {environ["PYTEST_CURRENT_TEST"]}')
 
 During the test session pytest will set ``PYTEST_CURRENT_TEST`` to the current test
-:ref:`nodeid <nodeids>` and the current stage, which can be ``setup``, ``call``
-and ``teardown``.
+:ref:`nodeid <nodeids>` and the current stage, which can be ``setup``, ``call``,
+or ``teardown``.
 
 For example, when running a single test function named ``test_foo`` from ``foo_module.py``,
 ``PYTEST_CURRENT_TEST`` will be set to:

doc/en/flaky.rst

@@ -43,7 +43,8 @@ Xfail strict
 PYTEST_CURRENT_TEST
 ~~~~~~~~~~~~~~~~~~~
 
-:ref:`pytest current test env` may be useful for figuring out "which test got stuck".
+:envvar:`PYTEST_CURRENT_TEST` may be useful for figuring out "which test got stuck".
+See :ref:`pytest current test env` for more details.
 
 
 Plugins

doc/en/reference.rst

@@ -976,19 +976,16 @@ Environment Variables
 
 Environment variables that can be used to change pytest's behavior.
 
-PYTEST_ADDOPTS
-~~~~~~~~~~~~~~
+.. envvar:: PYTEST_ADDOPTS
 
 This contains a command-line (parsed by the py:mod:`shlex` module) that will be **prepended** to the command line given
 by the user, see :ref:`adding default options` for more information.
 
-PYTEST_DEBUG
-~~~~~~~~~~~~
+.. envvar:: PYTEST_DEBUG
 
 When set, pytest will print tracing and debug information.
 
-PYTEST_PLUGINS
-~~~~~~~~~~~~~~
+.. envvar:: PYTEST_PLUGINS
 
 Contains comma-separated list of modules that should be loaded as plugins:
 
@@ -996,14 +993,12 @@ Contains comma-separated list of modules that should be loaded as plugins:
 
     export PYTEST_PLUGINS=mymodule.plugin,xdist
 
-PYTEST_DISABLE_PLUGIN_AUTOLOAD
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.. envvar:: PYTEST_DISABLE_PLUGIN_AUTOLOAD
 
 When set, disables plugin auto-loading through setuptools entrypoints. Only explicitly specified plugins will be
 loaded.
 
-PYTEST_CURRENT_TEST
-~~~~~~~~~~~~~~~~~~~
+.. envvar:: PYTEST_CURRENT_TEST
 
 This is not meant to be set by users, but is set by pytest internally with the name of the current test so other
 processes can inspect it, see :ref:`pytest current test env` for more information.

src/_pytest/runner.py

@@ -151,9 +151,9 @@ def pytest_runtest_teardown(item, nextitem):
 
 def _update_current_test_var(item, when):
     """
-    Update PYTEST_CURRENT_TEST to reflect the current item and stage.
+    Update :envvar:`PYTEST_CURRENT_TEST` to reflect the current item and stage.
 
-    If ``when`` is None, delete PYTEST_CURRENT_TEST from the environment.
+    If ``when`` is None, delete ``PYTEST_CURRENT_TEST`` from the environment.
     """
     var_name = "PYTEST_CURRENT_TEST"
     if when: