Merge pull request #9115 from RonnyPfannschmidt/fix-regendoc

fix #8818 - run regendoc without tox cachedir

Author: RonnyPfannschmidt

changelog/8818.trivial.rst

@@ -0,0 +1 @@
+Ensure ``regendoc`` opts out of ``TOX_ENV`` cachedir selection to ensure independent example test runs.

doc/en/Makefile

@@ -34,6 +34,10 @@ REGENDOC_ARGS := \
 
 regen: REGENDOC_FILES:=*.rst */*.rst
 regen:
-	PYTHONDONTWRITEBYTECODE=1 PYTEST_ADDOPTS="-pno:hypothesis -Wignore::pytest.PytestUnknownMarkWarning" COLUMNS=76 regendoc --update ${REGENDOC_FILES} ${REGENDOC_ARGS}
+# need to reset cachedir to the non-tox default
+	PYTHONDONTWRITEBYTECODE=1 \
+	PYTEST_ADDOPTS="-pno:hypothesis -p no:hypothesispytest -Wignore::pytest.PytestUnknownMarkWarning -o cache_dir=.pytest_cache" \
+	COLUMNS=76 \
+	regendoc --update ${REGENDOC_FILES} ${REGENDOC_ARGS}
 
 .PHONY: regen

doc/en/builtin.rst

@@ -16,8 +16,13 @@ For information about fixtures, see :ref:`fixtures`. To see a complete list of a
 
 .. code-block:: pytest
 
-    $ pytest -q --fixtures
-    cache
+    $ pytest  --fixtures -v
+    =========================== test session starts ============================
+    platform linux -- Python 3.x.y, pytest-6.x.y, py-1.x.y, pluggy-1.x.y -- $PYTHON_PREFIX/bin/python
+    cachedir: .pytest_cache
+    rootdir: /home/sweet/project
+    collected 0 items
+    cache -- ../../../..$PYTHON_SITE/_pytest/cacheprovider.py:520
         Return a cache object that can persist state between testing sessions.
 
         cache.get(key, default)
@@ -28,48 +33,49 @@ For information about fixtures, see :ref:`fixtures`. To see a complete list of a
 
         Values can be any object handled by the json stdlib module.
 
-    capsys
+    capsys -- ../../../..$PYTHON_SITE/_pytest/capture.py:903
         Enable text capturing of writes to ``sys.stdout`` and ``sys.stderr``.
 
         The captured output is made available via ``capsys.readouterr()`` method
         calls, which return a ``(out, err)`` namedtuple.
         ``out`` and ``err`` will be ``text`` objects.
 
-    capsysbinary
+    capsysbinary -- ../../../..$PYTHON_SITE/_pytest/capture.py:920
         Enable bytes capturing of writes to ``sys.stdout`` and ``sys.stderr``.
 
         The captured output is made available via ``capsysbinary.readouterr()``
         method calls, which return a ``(out, err)`` namedtuple.
         ``out`` and ``err`` will be ``bytes`` objects.
 
-    capfd
+    capfd -- ../../../..$PYTHON_SITE/_pytest/capture.py:937
         Enable text capturing of writes to file descriptors ``1`` and ``2``.
 
         The captured output is made available via ``capfd.readouterr()`` method
         calls, which return a ``(out, err)`` namedtuple.
         ``out`` and ``err`` will be ``text`` objects.
 
-    capfdbinary
+    capfdbinary -- ../../../..$PYTHON_SITE/_pytest/capture.py:954
         Enable bytes capturing of writes to file descriptors ``1`` and ``2``.
 
         The captured output is made available via ``capfd.readouterr()`` method
         calls, which return a ``(out, err)`` namedtuple.
         ``out`` and ``err`` will be ``byte`` objects.
 
-    doctest_namespace [session scope]
+    doctest_namespace [session scope] -- ../../../..$PYTHON_SITE/_pytest/doctest.py:728
         Fixture that returns a :py:class:`dict` that will be injected into the
         namespace of doctests.
 
-    pytestconfig [session scope]
-        Session-scoped fixture that returns the :class:`pytest.Config` object.
+    pytestconfig [session scope] -- ../../../..$PYTHON_SITE/_pytest/fixtures.py:1372
+        Session-scoped fixture that returns the session's :class:`pytest.Config`
+        object.
 
         Example::
 
             def test_foo(pytestconfig):
                 if pytestconfig.getoption("verbose") > 0:
                     ...
 
-    record_property
+    record_property -- ../../../..$PYTHON_SITE/_pytest/junitxml.py:282
         Add extra properties to the calling test.
 
         User properties become part of the test report and are available to the
@@ -83,13 +89,13 @@ For information about fixtures, see :ref:`fixtures`. To see a complete list of a
             def test_function(record_property):
                 record_property("example_key", 1)
 
-    record_xml_attribute
+    record_xml_attribute -- ../../../..$PYTHON_SITE/_pytest/junitxml.py:305
         Add extra xml attributes to the tag for the calling test.
 
         The fixture is callable with ``name, value``. The value is
         automatically XML-encoded.
 
-    record_testsuite_property [session scope]
+    record_testsuite_property [session scope] -- ../../../..$PYTHON_SITE/_pytest/junitxml.py:343
         Record a new ``<property>`` tag as child of the root ``<testsuite>``.
 
         This is suitable to writing global information regarding the entire test
@@ -111,7 +117,7 @@ For information about fixtures, see :ref:`fixtures`. To see a complete list of a
             `pytest-xdist <https://github.com/pytest-dev/pytest-xdist>`__ plugin. See issue
             `#7767 <https://github.com/pytest-dev/pytest/issues/7767>`__ for details.
 
-    caplog
+    caplog -- ../../../..$PYTHON_SITE/_pytest/logging.py:491
         Access and control log capturing.
 
         Captured logs are available through the following properties/methods::
@@ -122,7 +128,7 @@ For information about fixtures, see :ref:`fixtures`. To see a complete list of a
         * caplog.record_tuples   -> list of (logger_name, level, message) tuples
         * caplog.clear()         -> clear captured records and formatted log output string
 
-    monkeypatch
+    monkeypatch -- ../../../..$PYTHON_SITE/_pytest/monkeypatch.py:29
         A convenient fixture for monkey-patching.
 
         The fixture provides these methods to modify objects, dictionaries or
@@ -141,19 +147,19 @@ For information about fixtures, see :ref:`fixtures`. To see a complete list of a
         fixture has finished. The ``raising`` parameter determines if a KeyError
         or AttributeError will be raised if the set/deletion operation has no target.
 
-    recwarn
+    recwarn -- ../../../..$PYTHON_SITE/_pytest/recwarn.py:29
         Return a :class:`WarningsRecorder` instance that records all warnings emitted by test functions.
 
         See https://docs.python.org/library/how-to/capture-warnings.html for information
         on warning categories.
 
-    tmpdir_factory [session scope]
+    tmpdir_factory [session scope] -- ../../../..$PYTHON_SITE/_pytest/tmpdir.py:210
         Return a :class:`pytest.TempdirFactory` instance for the test session.
 
-    tmp_path_factory [session scope]
+    tmp_path_factory [session scope] -- ../../../..$PYTHON_SITE/_pytest/tmpdir.py:217
         Return a :class:`pytest.TempPathFactory` instance for the test session.
 
-    tmpdir
+    tmpdir -- ../../../..$PYTHON_SITE/_pytest/tmpdir.py:232
         Return a temporary directory path object which is unique to each test
         function invocation, created as a sub directory of the base temporary
         directory.
@@ -163,11 +169,11 @@ For information about fixtures, see :ref:`fixtures`. To see a complete list of a
         ``--basetemp`` is used then it is cleared each session. See :ref:`base
         temporary directory`.
 
-        The returned object is a `py.path.local`_ path object.
+        The returned object is a `legacy_path`_ object.
 
-        .. _`py.path.local`: https://py.readthedocs.io/en/latest/path.html
+        .. _legacy_path: https://py.readthedocs.io/en/latest/path.html
 
-    tmp_path
+    tmp_path -- ../../../..$PYTHON_SITE/_pytest/tmpdir.py:250
         Return a temporary directory path object which is unique to each test
         function invocation, created as a sub directory of the base temporary
         directory.
@@ -180,7 +186,7 @@ For information about fixtures, see :ref:`fixtures`. To see a complete list of a
         The returned object is a :class:`pathlib.Path` object.
 
 
-    no tests ran in 0.12s
+    ========================== no tests ran in 0.12s ===========================
 
 You can also interactively ask for help, e.g. by typing on the Python interactive prompt something like:
 

doc/en/example/markers.rst

@@ -46,8 +46,8 @@ You can then restrict a test run to only run tests marked with ``webtest``:
     $ pytest -v -m webtest
     =========================== test session starts ============================
     platform linux -- Python 3.x.y, pytest-6.x.y, py-1.x.y, pluggy-1.x.y -- $PYTHON_PREFIX/bin/python
-    cachedir: $PYTHON_PREFIX/.pytest_cache
-    rootdir: $REGENDOC_TMPDIR
+    cachedir: .pytest_cache
+    rootdir: /home/sweet/project
     collecting ... collected 4 items / 3 deselected / 1 selected
 
     test_server.py::test_send_http PASSED                                [100%]
@@ -61,8 +61,8 @@ Or the inverse, running all tests except the webtest ones:
     $ pytest -v -m "not webtest"
     =========================== test session starts ============================
     platform linux -- Python 3.x.y, pytest-6.x.y, py-1.x.y, pluggy-1.x.y -- $PYTHON_PREFIX/bin/python
-    cachedir: $PYTHON_PREFIX/.pytest_cache
-    rootdir: $REGENDOC_TMPDIR
+    cachedir: .pytest_cache
+    rootdir: /home/sweet/project
     collecting ... collected 4 items / 1 deselected / 3 selected
 
     test_server.py::test_something_quick PASSED                          [ 33%]
@@ -83,8 +83,8 @@ tests based on their module, class, method, or function name:
     $ pytest -v test_server.py::TestClass::test_method
     =========================== test session starts ============================
     platform linux -- Python 3.x.y, pytest-6.x.y, py-1.x.y, pluggy-1.x.y -- $PYTHON_PREFIX/bin/python
-    cachedir: $PYTHON_PREFIX/.pytest_cache
-    rootdir: $REGENDOC_TMPDIR
+    cachedir: .pytest_cache
+    rootdir: /home/sweet/project
     collecting ... collected 1 item
 
     test_server.py::TestClass::test_method PASSED                        [100%]
@@ -98,8 +98,8 @@ You can also select on the class:
     $ pytest -v test_server.py::TestClass
     =========================== test session starts ============================
     platform linux -- Python 3.x.y, pytest-6.x.y, py-1.x.y, pluggy-1.x.y -- $PYTHON_PREFIX/bin/python
-    cachedir: $PYTHON_PREFIX/.pytest_cache
-    rootdir: $REGENDOC_TMPDIR
+    cachedir: .pytest_cache
+    rootdir: /home/sweet/project
     collecting ... collected 1 item
 
     test_server.py::TestClass::test_method PASSED                        [100%]
@@ -113,8 +113,8 @@ Or select multiple nodes:
     $ pytest -v test_server.py::TestClass test_server.py::test_send_http
     =========================== test session starts ============================
     platform linux -- Python 3.x.y, pytest-6.x.y, py-1.x.y, pluggy-1.x.y -- $PYTHON_PREFIX/bin/python
-    cachedir: $PYTHON_PREFIX/.pytest_cache
-    rootdir: $REGENDOC_TMPDIR
+    cachedir: .pytest_cache
+    rootdir: /home/sweet/project
     collecting ... collected 2 items
 
     test_server.py::TestClass::test_method PASSED                        [ 50%]
@@ -157,8 +157,8 @@ The expression matching is now case-insensitive.
     $ pytest -v -k http  # running with the above defined example module
     =========================== test session starts ============================
     platform linux -- Python 3.x.y, pytest-6.x.y, py-1.x.y, pluggy-1.x.y -- $PYTHON_PREFIX/bin/python
-    cachedir: $PYTHON_PREFIX/.pytest_cache
-    rootdir: $REGENDOC_TMPDIR
+    cachedir: .pytest_cache
+    rootdir: /home/sweet/project
     collecting ... collected 4 items / 3 deselected / 1 selected
 
     test_server.py::test_send_http PASSED                                [100%]
@@ -172,8 +172,8 @@ And you can also run all tests except the ones that match the keyword:
     $ pytest -k "not send_http" -v
     =========================== test session starts ============================
     platform linux -- Python 3.x.y, pytest-6.x.y, py-1.x.y, pluggy-1.x.y -- $PYTHON_PREFIX/bin/python
-    cachedir: $PYTHON_PREFIX/.pytest_cache
-    rootdir: $REGENDOC_TMPDIR
+    cachedir: .pytest_cache
+    rootdir: /home/sweet/project
     collecting ... collected 4 items / 1 deselected / 3 selected
 
     test_server.py::test_something_quick PASSED                          [ 33%]
@@ -189,8 +189,8 @@ Or to select "http" and "quick" tests:
     $ pytest -k "http or quick" -v
     =========================== test session starts ============================
     platform linux -- Python 3.x.y, pytest-6.x.y, py-1.x.y, pluggy-1.x.y -- $PYTHON_PREFIX/bin/python
-    cachedir: $PYTHON_PREFIX/.pytest_cache
-    rootdir: $REGENDOC_TMPDIR
+    cachedir: .pytest_cache
+    rootdir: /home/sweet/project
     collecting ... collected 4 items / 2 deselected / 2 selected
 
     test_server.py::test_send_http PASSED                                [ 50%]
@@ -244,7 +244,7 @@ You can ask which markers exist for your test suite - the list includes our just
 
     @pytest.mark.parametrize(argnames, argvalues): call a test function multiple times passing in different arguments in turn. argvalues generally needs to be a list of values if argnames specifies only one name or a list of tuples of values if argnames specifies multiple names. Example: @parametrize('arg1', [1,2]) would lead to two calls of the decorated test function, one with arg1=1 and another with arg1=2.see https://docs.pytest.org/en/stable/how-to/parametrize.html for more info and examples.
 
-    @pytest.mark.usefixtures(fixturename1, fixturename2, ...): mark tests as needing all of the specified fixtures. see https://docs.pytest.org/en/stable/how-to/fixtures.html#usefixtures
+    @pytest.mark.usefixtures(fixturename1, fixturename2, ...): mark tests as needing all of the specified fixtures. see https://docs.pytest.org/en/stable/explanation/fixtures.html#usefixtures
 
     @pytest.mark.tryfirst: mark a hook implementation function such that the plugin machinery will try to call it first/as early as possible.
 
@@ -398,8 +398,8 @@ the test needs:
     $ pytest -E stage2
     =========================== test session starts ============================
     platform linux -- Python 3.x.y, pytest-6.x.y, py-1.x.y, pluggy-1.x.y
-    cachedir: $PYTHON_PREFIX/.pytest_cache
-    rootdir: $REGENDOC_TMPDIR
+    cachedir: .pytest_cache
+    rootdir: /home/sweet/project
     collected 1 item
 
     test_someenv.py s                                                    [100%]
@@ -413,8 +413,8 @@ and here is one that specifies exactly the environment needed:
     $ pytest -E stage1
     =========================== test session starts ============================
     platform linux -- Python 3.x.y, pytest-6.x.y, py-1.x.y, pluggy-1.x.y
-    cachedir: $PYTHON_PREFIX/.pytest_cache
-    rootdir: $REGENDOC_TMPDIR
+    cachedir: .pytest_cache
+    rootdir: /home/sweet/project
     collected 1 item
 
     test_someenv.py .                                                    [100%]
@@ -488,7 +488,7 @@ The output is as follows:
 .. code-block:: pytest
 
     $ pytest -q -s
-    Mark(name='my_marker', args=(<function hello_world at 0xdeadbeef>,), kwargs={})
+    Mark(name='my_marker', args=(<function hello_world at 0xdeadbeef0001>,), kwargs={})
     .
     1 passed in 0.12s
 
@@ -606,8 +606,8 @@ then you will see two tests skipped and two executed tests as expected:
     $ pytest -rs # this option reports skip reasons
     =========================== test session starts ============================
     platform linux -- Python 3.x.y, pytest-6.x.y, py-1.x.y, pluggy-1.x.y
-    cachedir: $PYTHON_PREFIX/.pytest_cache
-    rootdir: $REGENDOC_TMPDIR
+    cachedir: .pytest_cache
+    rootdir: /home/sweet/project
     collected 4 items
 
     test_plat.py s.s.                                                    [100%]
@@ -623,8 +623,8 @@ Note that if you specify a platform via the marker-command line option like this
     $ pytest -m linux
     =========================== test session starts ============================
     platform linux -- Python 3.x.y, pytest-6.x.y, py-1.x.y, pluggy-1.x.y
-    cachedir: $PYTHON_PREFIX/.pytest_cache
-    rootdir: $REGENDOC_TMPDIR
+    cachedir: .pytest_cache
+    rootdir: /home/sweet/project
     collected 4 items / 3 deselected / 1 selected
 
     test_plat.py .                                                       [100%]
@@ -687,8 +687,8 @@ We can now use the ``-m option`` to select one set:
     $ pytest -m interface --tb=short
     =========================== test session starts ============================
     platform linux -- Python 3.x.y, pytest-6.x.y, py-1.x.y, pluggy-1.x.y
-    cachedir: $PYTHON_PREFIX/.pytest_cache
-    rootdir: $REGENDOC_TMPDIR
+    cachedir: .pytest_cache
+    rootdir: /home/sweet/project
     collected 4 items / 2 deselected / 2 selected
 
     test_module.py FF                                                    [100%]
@@ -714,8 +714,8 @@ or to select both "event" and "interface" tests:
     $ pytest -m "interface or event" --tb=short
     =========================== test session starts ============================
     platform linux -- Python 3.x.y, pytest-6.x.y, py-1.x.y, pluggy-1.x.y
-    cachedir: $PYTHON_PREFIX/.pytest_cache
-    rootdir: $REGENDOC_TMPDIR
+    cachedir: .pytest_cache
+    rootdir: /home/sweet/project
     collected 4 items / 1 deselected / 3 selected
 
     test_module.py FFF                                                   [100%]

doc/en/example/nonpython.rst

@@ -30,8 +30,8 @@ now execute the test specification:
     nonpython $ pytest test_simple.yaml
     =========================== test session starts ============================
     platform linux -- Python 3.x.y, pytest-6.x.y, py-1.x.y, pluggy-1.x.y
-    cachedir: $PYTHON_PREFIX/.pytest_cache
-    rootdir: $REGENDOC_TMPDIR/nonpython
+    cachedir: .pytest_cache
+    rootdir: /home/sweet/project/nonpython
     collected 2 items
 
     test_simple.yaml F.                                                  [100%]
@@ -67,8 +67,8 @@ consulted when reporting in ``verbose`` mode:
     nonpython $ pytest -v
     =========================== test session starts ============================
     platform linux -- Python 3.x.y, pytest-6.x.y, py-1.x.y, pluggy-1.x.y -- $PYTHON_PREFIX/bin/python
-    cachedir: $PYTHON_PREFIX/.pytest_cache
-    rootdir: $REGENDOC_TMPDIR/nonpython
+    cachedir: .pytest_cache
+    rootdir: /home/sweet/project/nonpython
     collecting ... collected 2 items
 
     test_simple.yaml::hello FAILED                                       [ 50%]
@@ -93,8 +93,8 @@ interesting to just look at the collection tree:
     nonpython $ pytest --collect-only
     =========================== test session starts ============================
     platform linux -- Python 3.x.y, pytest-6.x.y, py-1.x.y, pluggy-1.x.y
-    cachedir: $PYTHON_PREFIX/.pytest_cache
-    rootdir: $REGENDOC_TMPDIR/nonpython
+    cachedir: .pytest_cache
+    rootdir: /home/sweet/project/nonpython
     collected 2 items
 
     <Package nonpython>