Skip to content

doc: indent envvar bodies and add src-layout link #14181

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
him2him2 wants to merge 2 commits into from
+34 −29
Closed

doc: indent envvar bodies and add src-layout link #14181

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
e9899a8
doc: indent envvar bodies and add src-layout link
him2him2 Feb 11, 2026
9bb8ae1
Merge branch 'main' into doc-envvar-indent-and-layout-link
him2him2 Feb 11, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions doc/en/explanation/goodpractices.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 <https://packaging.python.org/en/latest/discussions/src-layout-vs-flat-layout/>`_
Copy link
Member

@webknjaz webknjaz Feb 11, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's a Sphinx site. We can just use intersphinx. Also, I was thinking of just linking the existing text. Not sure how others will feel about having this here. Let's see...

Copy link
Contributor Author

@him2him2 him2him2 Feb 11, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good point on both counts — switched to intersphinx (:doc:packaging:discussions/src-layout-vs-flat-layout) in the replacement PR. Happy to rework to an inline link if that's preferred.

The Python Packaging User Guide discusses the trade-offs between the ``src`` layout and flat layout.

Tests as part of application code
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Expand Down
58 changes: 29 additions & 29 deletions doc/en/reference/reference.rst
View file
Open in desktop
Copy link
Member

@webknjaz webknjaz Feb 11, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks like the render/structure got better: https://pytest--14181.org.readthedocs.build/en/14181/reference/reference.html#environment-variables. So the changes to this document improve it and I don't have any objections. But the changes in other file are up for discussion.

Tip

@him2him2 you may want to contribute a better example of using the .. envvar:: directive to Sphinx's own docs — they don't seem to make it clear that the directive accepts both the env var name and a blurb with explanation.

Copy link
Contributor Author

@him2him2 him2him2 Feb 11, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks — glad the rendering improved. Good idea about contributing a better envvar example upstream to Sphinx, I'll look into that.

Copy link
Contributor Author

@him2him2 him2him2 Feb 11, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Followed up on the Sphinx suggestion — opened sphinx-doc/sphinx#14295 to add an example to the .. envvar:: directive docs, following the same pattern as .. confval::. Thanks for the nudge!

Copy link
Member

@webknjaz webknjaz Feb 11, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Great! This practice is most common among maintainers and people who ended up gaining expertise in specific areas that are universally useful in many projects — trying to improve upstream and replicate similar contributions across many projects. This often results in a greater impact on the ecosystem and tooling.

Original file line number Diff line number Diff line change
Expand Up @@ -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 <packaging:guides/creating-and-discovering-plugins>`. Only plugins
explicitly specified in :envvar:`PYTEST_PLUGINS` or with :option:`-p` will be loaded.
See also :ref:`--disable-plugin-autoload <disable_plugin_autoload>`.
When set, disables plugin auto-loading through :std:doc:`entry point packaging
metadata <packaging:guides/creating-and-discovering-plugins>`. Only plugins
explicitly specified in :envvar:`PYTEST_PLUGINS` or with :option:`-p` will be loaded.
See also :ref:`--disable-plugin-autoload <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 <https://pygments.org/docs/styles/>`_ to use for the code output.
Sets a `pygment style <https://pygments.org/docs/styles/>`_ 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 <https://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 <https://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
----------
Expand Down