From 7cb397413f3d8270fad4de1004039d45cb1a841d Mon Sep 17 00:00:00 2001 From: Ran Benita Date: Wed, 5 Nov 2025 21:22:57 +0200 Subject: [PATCH 1/2] doc: restore missing "# content of pytest.toml" regendoc commands In 147467db1cd00cdb5e1e56b954bd2cf95ddedf4b I didn't realize they were significant. --- doc/en/example/markers.rst | 1 + doc/en/example/pythoncollection.rst | 5 +++++ doc/en/example/simple.rst | 1 + doc/en/explanation/goodpractices.rst | 1 + doc/en/how-to/doctest.rst | 1 + doc/en/how-to/fixtures.rst | 1 + doc/en/how-to/writing_plugins.rst | 1 + doc/en/reference/reference.rst | 1 + 8 files changed, 12 insertions(+) diff --git a/doc/en/example/markers.rst b/doc/en/example/markers.rst index ed830b9fb2e..48dfc5db5ef 100644 --- a/doc/en/example/markers.rst +++ b/doc/en/example/markers.rst @@ -243,6 +243,7 @@ Registering markers for your test suite is simple: .. code-block:: toml + # content of pytest.toml [pytest] markers = ["webtest: mark a test as a webtest.", "slow: mark test as slow."] diff --git a/doc/en/example/pythoncollection.rst b/doc/en/example/pythoncollection.rst index 5ff3ae20247..b8b59e006fe 100644 --- a/doc/en/example/pythoncollection.rst +++ b/doc/en/example/pythoncollection.rst @@ -94,6 +94,7 @@ You can set the :confval:`norecursedirs` option in a configuration file: .. code-block:: toml + # content of pytest.toml [pytest] norecursedirs = [".svn", "_build", "tmp*"] @@ -120,6 +121,7 @@ Here is an example: .. code-block:: toml + # content of pytest.toml # Example 1: have pytest look for "check" instead of "test" [pytest] python_files = ["check_*.py"] @@ -175,6 +177,7 @@ You can check for multiple glob patterns by adding a space between the patterns: .. code-block:: toml + # content of pytest.toml # Example 2: have pytest look for files with "test" and "example" [pytest] python_files = ["test_*.py", "example_*.py"] @@ -213,6 +216,7 @@ can make this change more permanently: .. code-block:: toml + # content of pytest.toml [pytest] addopts = ["--pyargs"] @@ -264,6 +268,7 @@ You can easily instruct ``pytest`` to discover tests from every Python file: .. code-block:: toml + # content of pytest.toml [pytest] python_files = ["*.py"] diff --git a/doc/en/example/simple.rst b/doc/en/example/simple.rst index 7effb480480..8af3bfaab06 100644 --- a/doc/en/example/simple.rst +++ b/doc/en/example/simple.rst @@ -15,6 +15,7 @@ progress output, you can write it into a configuration file: .. code-block:: toml + # content of pytest.toml [pytest] addopts = ["-ra", "-q"] diff --git a/doc/en/explanation/goodpractices.rst b/doc/en/explanation/goodpractices.rst index 1a4e3420875..c05cff2f4d5 100644 --- a/doc/en/explanation/goodpractices.rst +++ b/doc/en/explanation/goodpractices.rst @@ -100,6 +100,7 @@ To this end, add the following to your configuration file: .. code-block:: toml + # content of pytest.toml [pytest] addopts = ["--import-mode=importlib"] diff --git a/doc/en/how-to/doctest.rst b/doc/en/how-to/doctest.rst index 5a11a475abd..8a0a104d19b 100644 --- a/doc/en/how-to/doctest.rst +++ b/doc/en/how-to/doctest.rst @@ -74,6 +74,7 @@ putting them into a configuration file like this: .. code-block:: toml + # content of pytest.toml [pytest] addopts = ["--doctest-modules"] diff --git a/doc/en/how-to/fixtures.rst b/doc/en/how-to/fixtures.rst index 48b2653a0f6..bdb7432df80 100644 --- a/doc/en/how-to/fixtures.rst +++ b/doc/en/how-to/fixtures.rst @@ -1742,6 +1742,7 @@ into a configuration file: .. code-block:: toml + # content of pytest.toml [pytest] usefixtures = ["cleandir"] diff --git a/doc/en/how-to/writing_plugins.rst b/doc/en/how-to/writing_plugins.rst index d3ddf45c276..8a044ab7848 100644 --- a/doc/en/how-to/writing_plugins.rst +++ b/doc/en/how-to/writing_plugins.rst @@ -426,6 +426,7 @@ in our configuration file to tell pytest where to look for example files. .. code-block:: toml + # content of pytest.toml [pytest] pytester_example_dir = "." diff --git a/doc/en/reference/reference.rst b/doc/en/reference/reference.rst index 9e495e506fe..89e4d630011 100644 --- a/doc/en/reference/reference.rst +++ b/doc/en/reference/reference.rst @@ -1337,6 +1337,7 @@ passed multiple times. The expected format is ``name=value``. For example:: .. code-block:: toml + # content of pytest.toml [pytest] addopts = ["--maxfail=2", "-rf"] # exit after 2 failures, report fail info From d6d3e4a4760bcdc9c2078b015d5967937b1df602 Mon Sep 17 00:00:00 2001 From: Ran Benita Date: Wed, 5 Nov 2025 21:22:57 +0200 Subject: [PATCH 2/2] doc: fixes for regendoc Turns out regendoc doesn't work with the new `.. tab` changes. Undo the tabification in problematic cases for now. Ideally though, we fix regendoc and revert this. --- doc/en/example/markers.rst | 19 ++---- doc/en/example/pythoncollection.rst | 97 +++++++--------------------- doc/en/example/simple.rst | 18 ++---- doc/en/explanation/goodpractices.rst | 17 ++--- doc/en/how-to/doctest.rst | 18 ++---- doc/en/how-to/fixtures.rst | 18 ++---- doc/en/how-to/writing_plugins.rst | 17 ++--- doc/en/reference/reference.rst | 17 ++--- 8 files changed, 52 insertions(+), 169 deletions(-) diff --git a/doc/en/example/markers.rst b/doc/en/example/markers.rst index 48dfc5db5ef..c8f7c8c2fa2 100644 --- a/doc/en/example/markers.rst +++ b/doc/en/example/markers.rst @@ -239,22 +239,11 @@ Registering markers Registering markers for your test suite is simple: -.. tab:: toml +.. code-block:: toml - .. code-block:: toml - - # content of pytest.toml - [pytest] - markers = ["webtest: mark a test as a webtest.", "slow: mark test as slow."] - -.. tab:: ini - - .. code-block:: ini - - [pytest] - markers = - webtest: mark a test as a webtest. - slow: mark test as slow. + # content of pytest.toml + [pytest] + markers = ["webtest: mark a test as a webtest.", "slow: mark test as slow."] Multiple custom markers can be registered, by defining each one in its own line, as shown in above example. diff --git a/doc/en/example/pythoncollection.rst b/doc/en/example/pythoncollection.rst index b8b59e006fe..46d15557fa8 100644 --- a/doc/en/example/pythoncollection.rst +++ b/doc/en/example/pythoncollection.rst @@ -90,20 +90,11 @@ Changing directory recursion You can set the :confval:`norecursedirs` option in a configuration file: -.. tab:: toml +.. code-block:: toml - .. code-block:: toml - - # content of pytest.toml - [pytest] - norecursedirs = [".svn", "_build", "tmp*"] - -.. tab:: ini - - .. code-block:: ini - - [pytest] - norecursedirs = .svn _build tmp* + # content of pytest.toml + [pytest] + norecursedirs = [".svn", "_build", "tmp*"] This would tell ``pytest`` to not recurse into typical subversion or sphinx-build directories or into any ``tmp`` prefixed directory. @@ -117,26 +108,14 @@ the :confval:`python_files`, :confval:`python_classes` and :confval:`python_functions` in your :ref:`configuration file `. Here is an example: -.. tab:: toml - - .. code-block:: toml +.. code-block:: toml - # content of pytest.toml - # Example 1: have pytest look for "check" instead of "test" - [pytest] - python_files = ["check_*.py"] - python_classes = ["Check"] - python_functions = ["*_check"] - -.. tab:: ini - - .. code-block:: ini - - # Example 1: have pytest look for "check" instead of "test" - [pytest] - python_files = check_*.py - python_classes = Check - python_functions = *_check + # content of pytest.toml + # Example 1: have pytest look for "check" instead of "test" + [pytest] + python_files = ["check_*.py"] + python_classes = ["Check"] + python_functions = ["*_check"] This would make ``pytest`` look for tests in files that match the ``check_* .py`` glob-pattern, ``Check`` prefixes in classes, and functions and methods @@ -173,22 +152,12 @@ The test collection would look like this: You can check for multiple glob patterns by adding a space between the patterns: -.. tab:: toml - - .. code-block:: toml - - # content of pytest.toml - # Example 2: have pytest look for files with "test" and "example" - [pytest] - python_files = ["test_*.py", "example_*.py"] +.. code-block:: toml -.. tab:: ini - - .. code-block:: ini - - # Example 2: have pytest look for files with "test" and "example" - [pytest] - python_files = test_*.py example_*.py + # content of pytest.toml + # Example 2: have pytest look for files with "test" and "example" + [pytest] + python_files = ["test_*.py", "example_*.py"] .. note:: @@ -212,20 +181,11 @@ which would run the respective test module. Like with other options, through a configuration file and the :confval:`addopts` option you can make this change more permanently: -.. tab:: toml - - .. code-block:: toml - - # content of pytest.toml - [pytest] - addopts = ["--pyargs"] - -.. tab:: ini +.. code-block:: toml - .. code-block:: ini - - [pytest] - addopts = --pyargs + # content of pytest.toml + [pytest] + addopts = ["--pyargs"] Now a simple invocation of ``pytest NAME`` will check if NAME exists as an importable package/module and otherwise @@ -264,20 +224,11 @@ Customizing test collection You can easily instruct ``pytest`` to discover tests from every Python file: -.. tab:: toml - - .. code-block:: toml - - # content of pytest.toml - [pytest] - python_files = ["*.py"] - -.. tab:: ini - - .. code-block:: ini +.. code-block:: toml - [pytest] - python_files = *.py + # content of pytest.toml + [pytest] + python_files = ["*.py"] However, many projects will have a ``setup.py`` which they don't want to be imported. Moreover, there may files only importable by a specific python diff --git a/doc/en/example/simple.rst b/doc/en/example/simple.rst index 8af3bfaab06..928dcddae74 100644 --- a/doc/en/example/simple.rst +++ b/doc/en/example/simple.rst @@ -11,21 +11,11 @@ every time you use ``pytest``. For example, if you always want to see detailed info on skipped and xfailed tests, as well as have terser "dot" progress output, you can write it into a configuration file: -.. tab:: toml - - .. code-block:: toml - - # content of pytest.toml - [pytest] - addopts = ["-ra", "-q"] - -.. tab:: ini - - .. code-block:: ini - - [pytest] - addopts = -ra -q +.. code-block:: toml + # content of pytest.toml + [pytest] + addopts = ["-ra", "-q"] Alternatively, you can set a ``PYTEST_ADDOPTS`` environment variable to add command line options while the environment is in use: diff --git a/doc/en/explanation/goodpractices.rst b/doc/en/explanation/goodpractices.rst index c05cff2f4d5..d97dda06417 100644 --- a/doc/en/explanation/goodpractices.rst +++ b/doc/en/explanation/goodpractices.rst @@ -96,20 +96,11 @@ For new projects, we recommend to use ``importlib`` :ref:`import mode