Added how-to and reference directories.

Moved various documents into subdirectories, how-to and
reference.

Updated multiple links to use `:ref:` instead of `:doc:`,
meaning that files can henceforth be moved around without
breaking references.

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.

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

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 <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.
 

doc/en/getting-started.rst

@@ -1,3 +1,5 @@
+.. _get-started:
+
 Get Started
 ===================================
 

doc/en/how-to/monkeypatch.rst

@@ -1,3 +1,4 @@
+.. _monkeypatching:
 
 How to monkeypatch/mock modules and environments
 ================================================================

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`_.
 

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:
 

doc/en/index.rst

@@ -81,7 +81,7 @@ Features
 
 - Python 3.6+ and PyPy 3
 
-- Rich plugin architecture, with over 800+ :doc:`external plugins <plugin_list>` and thriving community
+- Rich plugin architecture, with over 800+ :ref:`external plugins <plugin-list>` and thriving community
 
 
 Documentation

doc/en/reference/doctest.rst

@@ -1,3 +1,4 @@
+.. _doctest:
 
 Doctest integration for modules and test files
 =========================================================

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``

doc/en/reference/plugin_list.rst

@@ -1,3 +1,5 @@
+.. _plugin-list:
+
 Plugins List
 ============
 

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 <doctest>`.
+   :ref:`See how pytest handles doctests <doctest>`.
 
 
 .. confval:: doctest_optionflags
 
    One or more doctest flag names from the standard ``doctest`` module.
-   :doc:`See how pytest handles doctests <doctest>`.
+   :ref:`See how pytest handles doctests <doctest>`.
 
 
 .. confval:: empty_parameter_set_mark

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 <plugin_list>` providing additional features
+* many :ref:`external plugins <plugin-list>` providing additional features
 
 All of these plugins implement :ref:`hooks <hook-reference>` and/or :ref:`fixtures <fixture>`
 to extend and add functionality.