diff --git a/changelog/5105.doc.rst b/changelog/5105.doc.rst index f0cc8bab7..71c1edc9f 100644 --- a/changelog/5105.doc.rst +++ b/changelog/5105.doc.rst @@ -1 +1 @@ -Add automatically generated :doc:`plugin_list`. The list is updated on a periodic schedule. +Add automatically generated :ref:`plugin-list`. The list is updated on a periodic schedule. diff --git a/doc/en/contents.rst b/doc/en/contents.rst index 1bcc7f12b..84b87a35f 100644 --- a/doc/en/contents.rst +++ b/doc/en/contents.rst @@ -23,18 +23,18 @@ How-to guides .. toctree:: :maxdepth: 2 - usage - existingtestsuite - assert - mark - monkeypatch - tmpdir - capture - skipping - parametrize - plugins - nose - bash-completion + how-to/usage + how-to/existingtestsuite + how-to/assert + how-to/mark + how-to/monkeypatch + how-to/tmpdir + how-to/capture + how-to/skipping + how-to/parametrize + how-to/plugins + how-to/nose + how-to/bash-completion Reference guides @@ -43,17 +43,17 @@ Reference guides .. toctree:: :maxdepth: 2 - fixture - warnings - doctest - cache - unittest - xunit_setup - plugin_list - writing_plugins - logging - customize - reference + reference/fixture + reference/warnings + reference/doctest + reference/cache + reference/unittest + reference/xunit_setup + reference/plugin_list + reference/writing_plugins + reference/logging + reference/customize + reference/reference Further topics diff --git a/doc/en/example/index.rst b/doc/en/example/index.rst index 6876082d4..71e855534 100644 --- a/doc/en/example/index.rst +++ b/doc/en/example/index.rst @@ -13,12 +13,12 @@ answers. For basic examples, see -- :doc:`../getting-started` for basic introductory examples +- :ref:`get-started` for basic introductory examples - :ref:`assert` for basic assertion examples - :ref:`Fixtures ` for basic fixture/setup examples - :ref:`parametrize` for basic test function parametrization -- :doc:`../unittest` for basic unittest integration -- :doc:`../nose` for basic nosetests integration +- :ref:`unittest` for basic unittest integration +- :ref:`noseintegration` for basic nosetests integration The following examples aim at various use cases you might encounter. diff --git a/doc/en/getting-started.rst b/doc/en/getting-started.rst index fad682554..32ded5539 100644 --- a/doc/en/getting-started.rst +++ b/doc/en/getting-started.rst @@ -1,3 +1,5 @@ +.. _get-started: + Get Started =================================== diff --git a/doc/en/assert.rst b/doc/en/how-to/assert.rst similarity index 100% rename from doc/en/assert.rst rename to doc/en/how-to/assert.rst diff --git a/doc/en/bash-completion.rst b/doc/en/how-to/bash-completion.rst similarity index 100% rename from doc/en/bash-completion.rst rename to doc/en/how-to/bash-completion.rst diff --git a/doc/en/capture.rst b/doc/en/how-to/capture.rst similarity index 100% rename from doc/en/capture.rst rename to doc/en/how-to/capture.rst diff --git a/doc/en/existingtestsuite.rst b/doc/en/how-to/existingtestsuite.rst similarity index 100% rename from doc/en/existingtestsuite.rst rename to doc/en/how-to/existingtestsuite.rst diff --git a/doc/en/mark.rst b/doc/en/how-to/mark.rst similarity index 100% rename from doc/en/mark.rst rename to doc/en/how-to/mark.rst diff --git a/doc/en/monkeypatch.rst b/doc/en/how-to/monkeypatch.rst similarity index 99% rename from doc/en/monkeypatch.rst rename to doc/en/how-to/monkeypatch.rst index d3c7689e4..f34ba7982 100644 --- a/doc/en/monkeypatch.rst +++ b/doc/en/how-to/monkeypatch.rst @@ -1,3 +1,4 @@ +.. _monkeypatching: How to monkeypatch/mock modules and environments ================================================================ diff --git a/doc/en/nose.rst b/doc/en/how-to/nose.rst similarity index 100% rename from doc/en/nose.rst rename to doc/en/how-to/nose.rst diff --git a/doc/en/parametrize.rst b/doc/en/how-to/parametrize.rst similarity index 100% rename from doc/en/parametrize.rst rename to doc/en/how-to/parametrize.rst diff --git a/doc/en/plugins.rst b/doc/en/how-to/plugins.rst similarity index 99% rename from doc/en/plugins.rst rename to doc/en/how-to/plugins.rst index ade51abad..60c442c1f 100644 --- a/doc/en/plugins.rst +++ b/doc/en/how-to/plugins.rst @@ -58,7 +58,7 @@ Here is a little annotated list for some popular plugins: To see a complete list of all plugins with their latest testing status against different pytest and Python versions, please visit -:doc:`plugin_list`. +:ref:`plugin-list`. You may also discover more plugins through a `pytest- pypi.org search`_. diff --git a/doc/en/skipping.rst b/doc/en/how-to/skipping.rst similarity index 99% rename from doc/en/skipping.rst rename to doc/en/how-to/skipping.rst index 66db74a1f..263732632 100644 --- a/doc/en/skipping.rst +++ b/doc/en/how-to/skipping.rst @@ -365,7 +365,7 @@ Examples Here is a simple test file with the several usages: -.. literalinclude:: example/xfail_demo.py +.. literalinclude:: /example/xfail_demo.py Running it with the report-on-xfail option gives this output: diff --git a/doc/en/tmpdir.rst b/doc/en/how-to/tmpdir.rst similarity index 100% rename from doc/en/tmpdir.rst rename to doc/en/how-to/tmpdir.rst diff --git a/doc/en/usage.rst b/doc/en/how-to/usage.rst similarity index 100% rename from doc/en/usage.rst rename to doc/en/how-to/usage.rst diff --git a/doc/en/index.rst b/doc/en/index.rst index 5060d9720..102426d46 100644 --- a/doc/en/index.rst +++ b/doc/en/index.rst @@ -81,7 +81,7 @@ Features - Python 3.6+ and PyPy 3 -- Rich plugin architecture, with over 800+ :doc:`external plugins ` and thriving community +- Rich plugin architecture, with over 800+ :ref:`external plugins ` and thriving community Documentation diff --git a/doc/en/cache.rst b/doc/en/reference/cache.rst similarity index 100% rename from doc/en/cache.rst rename to doc/en/reference/cache.rst diff --git a/doc/en/customize.rst b/doc/en/reference/customize.rst similarity index 100% rename from doc/en/customize.rst rename to doc/en/reference/customize.rst diff --git a/doc/en/doctest.rst b/doc/en/reference/doctest.rst similarity index 99% rename from doc/en/doctest.rst rename to doc/en/reference/doctest.rst index 486868bb8..b6ef1f5b8 100644 --- a/doc/en/doctest.rst +++ b/doc/en/reference/doctest.rst @@ -1,3 +1,4 @@ +.. _doctest: Doctest integration for modules and test files ========================================================= diff --git a/doc/en/fixture.rst b/doc/en/reference/fixture.rst similarity index 98% rename from doc/en/fixture.rst rename to doc/en/reference/fixture.rst index 50bc9ee8e..0fc25118b 100644 --- a/doc/en/fixture.rst +++ b/doc/en/reference/fixture.rst @@ -1188,12 +1188,12 @@ long as the test requesting them can see all fixtures involved. For example, here's a test file with a fixture (``outer``) that requests a fixture (``inner``) from a scope it wasn't defined in: -.. literalinclude:: example/fixtures/test_fixtures_request_different_scope.py +.. literalinclude:: /example/fixtures/test_fixtures_request_different_scope.py From the tests' perspectives, they have no problem seeing each of the fixtures they're dependent on: -.. image:: example/fixtures/test_fixtures_request_different_scope.svg +.. image:: /example/fixtures/test_fixtures_request_different_scope.svg :align: center So when they run, ``outer`` will have no problem finding ``inner``, because @@ -1270,7 +1270,7 @@ For example, given a test file structure like this: The boundaries of the scopes can be visualized like this: -.. image:: example/fixtures/fixture_availability.svg +.. image:: /example/fixtures/fixture_availability.svg :align: center The directories become their own sort of scope where fixtures that are defined @@ -1346,7 +1346,7 @@ If ``plugin_a`` is installed and provides the fixture ``a_fix``, and ``plugin_b`` is installed and provides the fixture ``b_fix``, then this is what the test's search for fixtures would look like: -.. image:: example/fixtures/fixture_availability_plugins.svg +.. image:: /example/fixtures/fixture_availability_plugins.svg :align: center pytest will only search for ``a_fix`` and ``b_fix`` in the plugins after @@ -1401,13 +1401,13 @@ Within a function request for fixtures, those of higher-scopes (such as Here's an example: -.. literalinclude:: example/fixtures/test_fixtures_order_scope.py +.. literalinclude:: /example/fixtures/test_fixtures_order_scope.py The test will pass because the larger scoped fixtures are executing first. The order breaks down to this: -.. image:: example/fixtures/test_fixtures_order_scope.svg +.. image:: /example/fixtures/test_fixtures_order_scope.svg :align: center Fixtures of the same order execute based on dependencies @@ -1421,17 +1421,17 @@ sure it is executed after ``b``. For example: -.. literalinclude:: example/fixtures/test_fixtures_order_dependencies.py +.. literalinclude:: /example/fixtures/test_fixtures_order_dependencies.py If we map out what depends on what, we get something that look like this: -.. image:: example/fixtures/test_fixtures_order_dependencies.svg +.. image:: /example/fixtures/test_fixtures_order_dependencies.svg :align: center The rules provided by each fixture (as to what fixture(s) each one has to come after) are comprehensive enough that it can be flattened to this: -.. image:: example/fixtures/test_fixtures_order_dependencies_flat.svg +.. image:: /example/fixtures/test_fixtures_order_dependencies_flat.svg :align: center Enough information has to be provided through these requests in order for pytest @@ -1442,7 +1442,7 @@ could go with any one of those interpretations at any point. For example, if ``d`` didn't request ``c``, i.e.the graph would look like this: -.. image:: example/fixtures/test_fixtures_order_dependencies_unclear.svg +.. image:: /example/fixtures/test_fixtures_order_dependencies_unclear.svg :align: center Because nothing requested ``c`` other than ``g``, and ``g`` also requests ``f``, @@ -1479,11 +1479,11 @@ non-autouse fixtures within that scope. So if the test file looked like this: -.. literalinclude:: example/fixtures/test_fixtures_order_autouse.py +.. literalinclude:: /example/fixtures/test_fixtures_order_autouse.py the graph would look like this: -.. image:: example/fixtures/test_fixtures_order_autouse.svg +.. image:: /example/fixtures/test_fixtures_order_autouse.svg :align: center Because ``c`` can now be put above ``d`` in the graph, pytest can once again @@ -1496,12 +1496,12 @@ Be careful with autouse, though, as an autouse fixture will automatically execute for every test that can reach it, even if they don't request it. For example, consider this file: -.. literalinclude:: example/fixtures/test_fixtures_order_autouse_multiple_scopes.py +.. literalinclude:: /example/fixtures/test_fixtures_order_autouse_multiple_scopes.py Even though nothing in ``TestClassWithC1Request`` is requesting ``c1``, it still is executed for the tests inside it anyway: -.. image:: example/fixtures/test_fixtures_order_autouse_multiple_scopes.svg +.. image:: /example/fixtures/test_fixtures_order_autouse_multiple_scopes.svg :align: center But just because one autouse fixture requested a non-autouse fixture, that @@ -1512,11 +1512,11 @@ fixture) can apply to. For example, take a look at this test file: -.. literalinclude:: example/fixtures/test_fixtures_order_autouse_temp_effects.py +.. literalinclude:: /example/fixtures/test_fixtures_order_autouse_temp_effects.py It would break down to something like this: -.. image:: example/fixtures/test_fixtures_order_autouse_temp_effects.svg +.. image:: /example/fixtures/test_fixtures_order_autouse_temp_effects.svg :align: center For ``test_req`` and ``test_no_req`` inside ``TestClassWithAutouse``, ``c3`` diff --git a/doc/en/logging.rst b/doc/en/reference/logging.rst similarity index 100% rename from doc/en/logging.rst rename to doc/en/reference/logging.rst diff --git a/doc/en/plugin_list.rst b/doc/en/reference/plugin_list.rst similarity index 99% rename from doc/en/plugin_list.rst rename to doc/en/reference/plugin_list.rst index 8426f469c..b433d3f9a 100644 --- a/doc/en/plugin_list.rst +++ b/doc/en/reference/plugin_list.rst @@ -1,3 +1,5 @@ +.. _plugin-list: + Plugins List ============ diff --git a/doc/en/reference.rst b/doc/en/reference/reference.rst similarity index 98% rename from doc/en/reference.rst rename to doc/en/reference/reference.rst index 9ad82b3e4..d18150bac 100644 --- a/doc/en/reference.rst +++ b/doc/en/reference/reference.rst @@ -136,7 +136,7 @@ Add warning filters to marked test items. pytest.mark.parametrize ~~~~~~~~~~~~~~~~~~~~~~~ -**Tutorial**: :doc:`parametrize`. +:ref:`parametrize`. This mark has the same signature as :py:meth:`pytest.Metafunc.parametrize`; see there. @@ -146,7 +146,7 @@ This mark has the same signature as :py:meth:`pytest.Metafunc.parametrize`; see pytest.mark.skip ~~~~~~~~~~~~~~~~ -**Tutorial**: :ref:`skip`. +:ref:`skip`. Unconditionally skip a test function. @@ -160,7 +160,7 @@ Unconditionally skip a test function. pytest.mark.skipif ~~~~~~~~~~~~~~~~~~ -**Tutorial**: :ref:`skipif`. +:ref:`skipif`. Skip a test function if a condition is ``True``. @@ -325,7 +325,7 @@ Under the hood, the cache plugin uses the simple capsys ~~~~~~ -**Tutorial**: :doc:`capture`. +:ref:`captures`. .. autofunction:: _pytest.capture.capsys() :no-auto-options: @@ -350,7 +350,7 @@ capsys capsysbinary ~~~~~~~~~~~~ -**Tutorial**: :doc:`capture`. +:ref:`captures`. .. autofunction:: _pytest.capture.capsysbinary() :no-auto-options: @@ -372,7 +372,7 @@ capsysbinary capfd ~~~~~~ -**Tutorial**: :doc:`capture`. +:ref:`captures`. .. autofunction:: _pytest.capture.capfd() :no-auto-options: @@ -394,7 +394,7 @@ capfd capfdbinary ~~~~~~~~~~~~ -**Tutorial**: :doc:`capture`. +:ref:`captures`. .. autofunction:: _pytest.capture.capfdbinary() :no-auto-options: @@ -416,7 +416,7 @@ capfdbinary doctest_namespace ~~~~~~~~~~~~~~~~~ -**Tutorial**: :doc:`doctest`. +:ref:`doctest`. .. autofunction:: _pytest.doctest.doctest_namespace() @@ -436,7 +436,7 @@ doctest_namespace request ~~~~~~~ -**Tutorial**: :ref:`request example`. +:ref:`request example`. The ``request`` fixture is a special fixture providing information of the requesting test function. @@ -477,7 +477,7 @@ record_testsuite_property caplog ~~~~~~ -**Tutorial**: :doc:`logging`. +:ref:`logging`. .. autofunction:: _pytest.logging.caplog() :no-auto-options: @@ -493,7 +493,7 @@ caplog monkeypatch ~~~~~~~~~~~ -**Tutorial**: :doc:`monkeypatch`. +:ref:`monkeypatching`. .. autofunction:: _pytest.monkeypatch.monkeypatch() :no-auto-options: @@ -576,7 +576,7 @@ Each recorded warning is an instance of :class:`warnings.WarningMessage`. tmp_path ~~~~~~~~ -**Tutorial**: :doc:`tmpdir` +:ref:`tmpdir` .. autofunction:: _pytest.tmpdir.tmp_path() :no-auto-options: @@ -587,7 +587,7 @@ tmp_path tmp_path_factory ~~~~~~~~~~~~~~~~ -**Tutorial**: :ref:`tmp_path_factory example` +:ref:`tmp_path_factory example` .. _`tmp_path_factory factory api`: @@ -601,7 +601,7 @@ tmp_path_factory tmpdir ~~~~~~ -**Tutorial**: :doc:`tmpdir` +:ref:`tmpdir` .. autofunction:: _pytest.tmpdir.tmpdir() :no-auto-options: @@ -612,7 +612,7 @@ tmpdir tmpdir_factory ~~~~~~~~~~~~~~ -**Tutorial**: :ref:`tmpdir factory example` +:ref:`tmpdir factory example` .. _`tmpdir factory api`: @@ -626,7 +626,7 @@ tmpdir_factory Hooks ----- -**Tutorial**: :doc:`writing_plugins`. +:ref:`writing-plugins`. .. currentmodule:: _pytest.hookspec @@ -1178,13 +1178,13 @@ passed multiple times. The expected format is ``name=value``. For example:: Default encoding to use to decode text files with docstrings. - :doc:`See how pytest handles doctests `. + :ref:`See how pytest handles doctests `. .. confval:: doctest_optionflags One or more doctest flag names from the standard ``doctest`` module. - :doc:`See how pytest handles doctests `. + :ref:`See how pytest handles doctests `. .. confval:: empty_parameter_set_mark diff --git a/doc/en/unittest.rst b/doc/en/reference/unittest.rst similarity index 100% rename from doc/en/unittest.rst rename to doc/en/reference/unittest.rst diff --git a/doc/en/warnings.rst b/doc/en/reference/warnings.rst similarity index 100% rename from doc/en/warnings.rst rename to doc/en/reference/warnings.rst diff --git a/doc/en/writing_plugins.rst b/doc/en/reference/writing_plugins.rst similarity index 99% rename from doc/en/writing_plugins.rst rename to doc/en/reference/writing_plugins.rst index 92a3dd7dd..b4d9f49ff 100644 --- a/doc/en/writing_plugins.rst +++ b/doc/en/reference/writing_plugins.rst @@ -122,7 +122,7 @@ you can copy from: * a custom collection example plugin: :ref:`yaml plugin` * builtin plugins which provide pytest's own functionality -* many :doc:`external plugins ` providing additional features +* many :ref:`external plugins ` providing additional features All of these plugins implement :ref:`hooks ` and/or :ref:`fixtures ` to extend and add functionality. diff --git a/doc/en/xunit_setup.rst b/doc/en/reference/xunit_setup.rst similarity index 100% rename from doc/en/xunit_setup.rst rename to doc/en/reference/xunit_setup.rst