From aae0579bcde9cf073d2e6b01399b6296299527fa Mon Sep 17 00:00:00 2001
From: Daniel Hahler <git@thequod.de>
Date: Fri, 27 Mar 2020 02:40:25 +0100
Subject: [PATCH] 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 |  8 ++++----
 doc/en/flaky.rst          |  3 ++-
 doc/en/reference.rst      | 15 +++++----------
 src/_pytest/runner.py     |  4 ++--
 4 files changed, 13 insertions(+), 17 deletions(-)

diff --git a/doc/en/example/simple.rst b/doc/en/example/simple.rst
index 984afb152..3282bbda5 100644
--- a/doc/en/example/simple.rst
+++ b/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:
diff --git a/doc/en/flaky.rst b/doc/en/flaky.rst
index 0f0eecab0..c246f4d9c 100644
--- a/doc/en/flaky.rst
+++ b/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
diff --git a/doc/en/reference.rst b/doc/en/reference.rst
index 02b2f1815..20d224379 100644
--- a/doc/en/reference.rst
+++ b/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.
diff --git a/src/_pytest/runner.py b/src/_pytest/runner.py
index 412ea44a8..7124996c8 100644
--- a/src/_pytest/runner.py
+++ b/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: