doc: add list of fixtures to start of fixture chapter (#6696)

- Add list of fixtures to start of fixture chapter
- Add "fixture" cross ref type

AUTHORS

@@ -145,6 +145,7 @@ Joshua Bronson
 Jurko Gospodnetić
 Justyna Janczyszyn
 Kale Kundert
+Karl O. Pinc
 Katarzyna Jachim
 Katerina Koukiou
 Kevin Cox

changelog/6696.doc.rst

@@ -0,0 +1 @@
+Add list of fixtures to start of fixture chapter.

doc/en/cache.rst

@@ -251,7 +251,7 @@ the cache and nothing will be printed:
     test_caching.py:20: AssertionError
     1 failed in 0.12s
 
-See the :ref:`cache-api` for more details.
+See the :fixture:`cache-api` for more details.
 
 
 Inspecting Cache content

doc/en/changelog.rst

@@ -180,7 +180,7 @@ Features
   rather than implicitly.
 
 
-- `#5914 <https://github.com/pytest-dev/pytest/issues/5914>`_: :ref:`testdir` learned two new functions, :py:func:`~_pytest.pytester.LineMatcher.no_fnmatch_line` and
+- `#5914 <https://github.com/pytest-dev/pytest/issues/5914>`_: :fixture:`testdir` learned two new functions, :py:func:`~_pytest.pytester.LineMatcher.no_fnmatch_line` and
   :py:func:`~_pytest.pytester.LineMatcher.no_re_match_line`.
 
   The functions are used to ensure the captured text *does not* match the given

doc/en/conf.py

@@ -373,10 +373,18 @@ def configure_logging(app: "sphinx.application.Sphinx") -> None:
 def setup(app: "sphinx.application.Sphinx") -> None:
     # from sphinx.ext.autodoc import cut_lines
     # app.connect('autodoc-process-docstring', cut_lines(4, what=['module']))
+    app.add_crossref_type(
+        "fixture",
+        "fixture",
+        objname="built-in fixture",
+        indextemplate="pair: %s; fixture",
+    )
+
     app.add_object_type(
         "confval",
         "confval",
         objname="configuration value",
         indextemplate="pair: %s; configuration value",
     )
+
     configure_logging(app)

doc/en/fixture.rst

@@ -40,6 +40,74 @@ both styles, moving incrementally from classic to new style, as you
 prefer.  You can also start out from existing :ref:`unittest.TestCase
 style <unittest.TestCase>` or :ref:`nose based <nosestyle>` projects.
 
+:ref:`Fixtures <fixtures-api>` are defined using the
+:ref:`@pytest.fixture <pytest.fixture-api>` decorator, :ref:`described
+below <funcargs>`. Pytest has useful built-in fixtures, listed here
+for reference:
+
+   :fixture:`capfd`
+        Capture, as text, output to file descriptors ``1`` and ``2``.
+
+   :fixture:`capfdbinary`
+        Capture, as bytes, output to file descriptors ``1`` and ``2``.
+
+   :fixture:`caplog`
+        Control logging and access log entries.
+
+   :fixture:`capsys`
+        Capture, as text, output to ``sys.stdout`` and ``sys.stderr``.
+
+   :fixture:`capsysbinary`
+        Capture, as bytes, output to ``sys.stdout`` and ``sys.stderr``.
+
+   :fixture:`cache`
+        Store and retrieve values across pytest runs.
+
+   :fixture:`doctest_namespace`
+        Provide a dict injected into the docstests namespace.
+
+   :fixture:`monkeypatch`
+       Temporarily modify classes, functions, dictionaries,
+       ``os.environ``, and other objects.
+
+   :fixture:`pytestconfig`
+        Access to configuration values, pluginmanager and plugin hooks.
+
+   :fixture:`record_property`
+       Add extra properties to the test.
+
+   :fixture:`record_testsuite_property`
+       Add extra properties to the test suite.
+
+   :fixture:`recwarn`
+        Record warnings emitted by test functions.
+
+   :fixture:`request`
+       Provide information on the executing test function.
+
+   :fixture:`testdir`
+        Provide a temporary test directory to aid in running, and
+        testing, pytest plugins.
+
+   :fixture:`tmp_path`
+       Provide a :class:`pathlib.Path` object to a temporary directory
+       which is unique to each test function.
+
+   :fixture:`tmp_path_factory`
+        Make session-scoped temporary directories and return
+        :class:`pathlib.Path` objects.
+
+   :fixture:`tmpdir`
+        Provide a :class:`py.path.local` object to a temporary
+        directory which is unique to each test function;
+        replaced by :fixture:`tmp_path`.
+
+        .. _`py.path.local`: https://py.readthedocs.io/en/latest/path.html
+
+   :fixture:`tmpdir_factory`
+        Make session-scoped temporary directories and return
+        :class:`py.path.local` objects;
+        replaced by :fixture:`tmp_path_factory`.
 
 .. _`funcargs`:
 .. _`funcarg mechanism`:

doc/en/reference.rst

@@ -243,6 +243,8 @@ Will create and attach a :class:`Mark <_pytest.mark.structures.Mark>` object to
     mark.kwargs == {"method": "thread"}
 
 
+.. _`fixtures-api`:
+
 Fixtures
 --------
 
@@ -273,6 +275,8 @@ Example of a fixture requiring another fixture:
 For more details, consult the full :ref:`fixtures docs <fixture>`.
 
 
+.. _`pytest.fixture-api`:
+
 @pytest.fixture
 ~~~~~~~~~~~~~~~
 
@@ -280,7 +284,7 @@ For more details, consult the full :ref:`fixtures docs <fixture>`.
     :decorator:
 
 
-.. _`cache-api`:
+.. fixture:: cache
 
 config.cache
 ~~~~~~~~~~~~
@@ -301,6 +305,8 @@ Under the hood, the cache plugin uses the simple
 .. automethod:: Cache.makedir
 
 
+.. fixture:: capsys
+
 capsys
 ~~~~~~
 
@@ -326,6 +332,8 @@ capsys
     :members:
 
 
+.. fixture:: capsysbinary
+
 capsysbinary
 ~~~~~~~~~~~~
 
@@ -346,6 +354,8 @@ capsysbinary
             assert captured.out == b"hello\n"
 
 
+.. fixture:: capfd
+
 capfd
 ~~~~~~
 
@@ -366,6 +376,8 @@ capfd
             assert captured.out == "hello\n"
 
 
+.. fixture:: capfdbinary
+
 capfdbinary
 ~~~~~~~~~~~~
 
@@ -386,6 +398,8 @@ capfdbinary
             assert captured.out == b"hello\n"
 
 
+.. fixture:: doctest_namespace
+
 doctest_namespace
 ~~~~~~~~~~~~~~~~~
 
@@ -404,6 +418,8 @@ doctest_namespace
     For more details: :ref:`doctest_namespace`.
 
 
+.. fixture:: request
+
 request
 ~~~~~~~
 
@@ -415,12 +431,16 @@ The ``request`` fixture is a special fixture providing information of the reques
     :members:
 
 
+.. fixture:: pytestconfig
+
 pytestconfig
 ~~~~~~~~~~~~
 
 .. autofunction:: _pytest.fixtures.pytestconfig()
 
 
+.. fixture:: record_property
+
 record_property
 ~~~~~~~~~~~~~~~~~~~
 
@@ -429,6 +449,8 @@ record_property
 .. autofunction:: _pytest.junitxml.record_property()
 
 
+.. fixture:: record_testsuite_property
+
 record_testsuite_property
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -436,6 +458,9 @@ record_testsuite_property
 
 .. autofunction:: _pytest.junitxml.record_testsuite_property()
 
+
+.. fixture:: caplog
+
 caplog
 ~~~~~~
 
@@ -450,6 +475,8 @@ caplog
     :members:
 
 
+.. fixture:: monkeypatch
+
 monkeypatch
 ~~~~~~~~~~~
 
@@ -465,7 +492,8 @@ monkeypatch
 .. autoclass:: _pytest.monkeypatch.MonkeyPatch
     :members:
 
-.. _testdir:
+
+.. fixture:: testdir
 
 testdir
 ~~~~~~~
@@ -493,6 +521,8 @@ To use it, include in your top-most ``conftest.py`` file:
     :members:
 
 
+.. fixture:: recwarn
+
 recwarn
 ~~~~~~~
 
@@ -516,6 +546,8 @@ Each recorded warning is an instance of :class:`warnings.WarningMessage`.
     differently; see :ref:`ensuring_function_triggers`.
 
 
+.. fixture:: tmp_path
+
 tmp_path
 ~~~~~~~~
 
@@ -527,6 +559,8 @@ tmp_path
     :no-auto-options:
 
 
+.. fixture:: tmp_path_factory
+
 tmp_path_factory
 ~~~~~~~~~~~~~~~~
 
@@ -542,6 +576,8 @@ tmp_path_factory
 .. automethod:: TempPathFactory.getbasetemp
 
 
+.. fixture:: tmpdir
+
 tmpdir
 ~~~~~~
 
@@ -553,6 +589,8 @@ tmpdir
     :no-auto-options:
 
 
+.. fixture:: tmpdir_factory
+
 tmpdir_factory
 ~~~~~~~~~~~~~~