From e9899a8225f070872b107ca0eb2ae197c54692eb Mon Sep 17 00:00:00 2001 From: ron Date: Wed, 11 Feb 2026 09:30:17 -0500 Subject: [PATCH] doc: indent envvar bodies and add src-layout link Indent the body text of all ``.. envvar::`` entries in ``reference.rst`` to match the 3-space indentation convention used by ``.. confval::`` entries in the same file. Add a ``.. seealso::`` link to the packaging.python.org src-layout vs flat-layout discussion in ``goodpractices.rst``. Follow-up to #14179. --- doc/en/explanation/goodpractices.rst | 5 +++ doc/en/reference/reference.rst | 58 ++++++++++++++-------------- 2 files changed, 34 insertions(+), 29 deletions(-) diff --git a/doc/en/explanation/goodpractices.rst b/doc/en/explanation/goodpractices.rst index 7c589b57033..afeeb5c2c0c 100644 --- a/doc/en/explanation/goodpractices.rst +++ b/doc/en/explanation/goodpractices.rst @@ -150,6 +150,11 @@ which are better explained in this excellent `blog post`_ by Ionel Cristian Măr See :ref:`pytest vs python -m pytest` for more information about the difference between calling ``pytest`` and ``python -m pytest``. +.. seealso:: + + `src layout vs flat layout `_ + The Python Packaging User Guide discusses the trade-offs between the ``src`` layout and flat layout. + Tests as part of application code ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/doc/en/reference/reference.rst b/doc/en/reference/reference.rst index 62ae3564e18..31e561a7d1f 100644 --- a/doc/en/reference/reference.rst +++ b/doc/en/reference/reference.rst @@ -1179,77 +1179,77 @@ Environment variables that can be used to change pytest's behavior. .. envvar:: CI -When set to a non-empty value, pytest acknowledges that is running in a CI process. See also :ref:`ci-pipelines`. + When set to a non-empty value, pytest acknowledges that is running in a CI process. See also :ref:`ci-pipelines`. .. envvar:: BUILD_NUMBER -When set to a non-empty value, pytest acknowledges that is running in a CI process. Alternative to :envvar:`CI`. See also :ref:`ci-pipelines`. + When set to a non-empty value, pytest acknowledges that is running in a CI process. Alternative to :envvar:`CI`. See also :ref:`ci-pipelines`. .. 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. + 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. .. envvar:: PYTEST_VERSION -This environment variable is defined at the start of the pytest session and is undefined afterwards. -It contains the value of ``pytest.__version__``, and among other things can be used to easily check if a code is running from within a pytest run. + This environment variable is defined at the start of the pytest session and is undefined afterwards. + It contains the value of ``pytest.__version__``, and among other things can be used to easily check if a code is running from within a pytest run. .. 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. + 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. .. envvar:: PYTEST_DEBUG -When set, pytest will print tracing and debug information. + When set, pytest will print tracing and debug information. .. envvar:: PYTEST_DEBUG_TEMPROOT -Root for temporary directories produced by fixtures like :fixture:`tmp_path` -as discussed in :ref:`temporary directory location and retention`. + Root for temporary directories produced by fixtures like :fixture:`tmp_path` + as discussed in :ref:`temporary directory location and retention`. .. envvar:: PYTEST_DISABLE_PLUGIN_AUTOLOAD -When set, disables plugin auto-loading through :std:doc:`entry point packaging -metadata `. Only plugins -explicitly specified in :envvar:`PYTEST_PLUGINS` or with :option:`-p` will be loaded. -See also :ref:`--disable-plugin-autoload `. + When set, disables plugin auto-loading through :std:doc:`entry point packaging + metadata `. Only plugins + explicitly specified in :envvar:`PYTEST_PLUGINS` or with :option:`-p` will be loaded. + See also :ref:`--disable-plugin-autoload `. .. envvar:: PYTEST_PLUGINS -Contains comma-separated list of modules that should be loaded as plugins: + Contains comma-separated list of modules that should be loaded as plugins: -.. code-block:: bash + .. code-block:: bash - export PYTEST_PLUGINS=mymodule.plugin,xdist + export PYTEST_PLUGINS=mymodule.plugin,xdist -See also :option:`-p`. + See also :option:`-p`. .. envvar:: PYTEST_THEME -Sets a `pygment style `_ to use for the code output. + Sets a `pygment style `_ to use for the code output. .. envvar:: PYTEST_THEME_MODE -Sets the :envvar:`PYTEST_THEME` to be either *dark* or *light*. + Sets the :envvar:`PYTEST_THEME` to be either *dark* or *light*. .. envvar:: PY_COLORS -When set to ``1``, pytest will use color in terminal output. -When set to ``0``, pytest will not use color. -``PY_COLORS`` takes precedence over ``NO_COLOR`` and ``FORCE_COLOR``. + When set to ``1``, pytest will use color in terminal output. + When set to ``0``, pytest will not use color. + ``PY_COLORS`` takes precedence over ``NO_COLOR`` and ``FORCE_COLOR``. .. envvar:: NO_COLOR -When set to a non-empty string (regardless of value), pytest will not use color in terminal output. -``PY_COLORS`` takes precedence over ``NO_COLOR``, which takes precedence over ``FORCE_COLOR``. -See `no-color.org `__ for other libraries supporting this community standard. + When set to a non-empty string (regardless of value), pytest will not use color in terminal output. + ``PY_COLORS`` takes precedence over ``NO_COLOR``, which takes precedence over ``FORCE_COLOR``. + See `no-color.org `__ for other libraries supporting this community standard. .. envvar:: FORCE_COLOR -When set to a non-empty string (regardless of value), pytest will use color in terminal output. -``PY_COLORS`` and ``NO_COLOR`` take precedence over ``FORCE_COLOR``. + When set to a non-empty string (regardless of value), pytest will use color in terminal output. + ``PY_COLORS`` and ``NO_COLOR`` take precedence over ``FORCE_COLOR``. Exceptions ----------