Merge pull request #11678 from pytest-dev/doc-nitpicks

doc: fix some broken Sphinx references

Author: bluetech

changelog/9288.breaking.rst

@@ -1,4 +1,4 @@
-:func:`pytest.warns <warns>` now re-emits unmatched warnings when the context
+:func:`~pytest.warns` now re-emits unmatched warnings when the context
 closes -- previously it would consume all warnings, hiding those that were not
 matched by the function.
 

doc/en/backwards-compatibility.rst

@@ -22,7 +22,7 @@ b) transitional: the old and new API don't conflict
 
    We will only start the removal of deprecated functionality in major releases (e.g. if we deprecate something in 3.0 we will start to remove it in 4.0), and keep it around for at least two minor releases (e.g. if we deprecate something in 3.9 and 4.0 is the next release, we start to remove it in 5.0, not in 4.0).
 
-   A deprecated feature scheduled to be removed in major version X will use the warning class `PytestRemovedInXWarning` (a subclass of :class:`~pytest.PytestDeprecationwarning`).
+   A deprecated feature scheduled to be removed in major version X will use the warning class `PytestRemovedInXWarning` (a subclass of :class:`~pytest.PytestDeprecationWarning`).
 
    When the deprecation expires (e.g. 4.0 is released), we won't remove the deprecated functionality immediately, but will use the standard warning filters to turn `PytestRemovedInXWarning` (e.g. `PytestRemovedIn4Warning`) into **errors** by default. This approach makes it explicit that removal is imminent, and still gives you time to turn the deprecated feature into a warning instead of an error so it can be dealt with in your own time. In the next minor release (e.g. 4.1), the feature will be effectively removed.
 

doc/en/changelog.rst

@@ -177,7 +177,7 @@ arguments they only pass on to the superclass.
     resolved in future versions as we slowly get rid of the :pypi:`py`
     dependency (see :issue:`9283` for a longer discussion).
 
-Due to the ongoing migration of methods like :meth:`~_pytest.Item.reportinfo`
+Due to the ongoing migration of methods like :meth:`~pytest.Item.reportinfo`
 which still is expected to return a ``py.path.local`` object, nodes still have
 both ``fspath`` (``py.path.local``) and ``path`` (``pathlib.Path``) attributes,
 no matter what argument was used in the constructor. We expect to deprecate the
@@ -336,7 +336,7 @@ Diamond inheritance between :class:`pytest.Collector` and :class:`pytest.Item`
 
 .. deprecated:: 7.0
 
-Defining a custom pytest node type which is both an :class:`pytest.Item <Item>` and a :class:`pytest.Collector <Collector>` (e.g. :class:`pytest.File <File>`) now issues a warning.
+Defining a custom pytest node type which is both an :class:`~pytest.Item` and a :class:`~pytest.Collector` (e.g. :class:`~pytest.File`) now issues a warning.
 It was never sanely supported and triggers hard to debug errors.
 
 Some plugins providing linting/code analysis have been using this as a hack.
@@ -348,8 +348,8 @@ Instead, a separate collector node should be used, which collects the item. See
 
 .. _uncooperative-constructors-deprecated:
 
-Constructors of custom :class:`pytest.Node` subclasses should take ``**kwargs``
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Constructors of custom :class:`~_pytest.nodes.Node` subclasses should take ``**kwargs``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 .. deprecated:: 7.0
 

doc/en/deprecations.rst

@@ -4,8 +4,6 @@
 Parametrizing tests
 =================================================
 
-.. currentmodule:: _pytest.python
-
 ``pytest`` allows to easily parametrize test functions.
 For basic docs, see :ref:`parametrize-basics`.
 
@@ -185,7 +183,7 @@ A quick port of "testscenarios"
 Here is a quick port to run tests configured with :pypi:`testscenarios`,
 an add-on from Robert Collins for the standard unittest framework. We
 only have to work a bit to construct the correct arguments for pytest's
-:py:func:`Metafunc.parametrize`:
+:py:func:`Metafunc.parametrize <pytest.Metafunc.parametrize>`:
 
 .. code-block:: python
 

doc/en/example/parametrize.rst

@@ -162,7 +162,7 @@ A note about fixture cleanup
 ----------------------------
 
 pytest does not do any special processing for :data:`SIGTERM <signal.SIGTERM>` and
-:data:`SIGQUIT <signal.SIGQUIT>` signals (:data:`SIGINT <signal.SIGINT>` is handled naturally
+``SIGQUIT`` signals (:data:`SIGINT <signal.SIGINT>` is handled naturally
 by the Python runtime via :class:`KeyboardInterrupt`), so fixtures that manage external resources which are important
 to be cleared when the Python process is terminated (by those signals) might leak resources.
 

doc/en/explanation/fixtures.rst

@@ -11,8 +11,6 @@ funcarg mechanism, see :ref:`historical funcargs and pytest.funcargs`.
 If you are new to pytest, then you can simply ignore this
 section and read the other sections.
 
-.. currentmodule:: _pytest
-
 Shortcomings of the previous ``pytest_funcarg__`` mechanism
 --------------------------------------------------------------
 

doc/en/funcarg_compare.rst

@@ -112,7 +112,7 @@ More details can be found in the :pull:`original PR <3317>`.
 .. note::
 
     in a future major release of pytest we will introduce class based markers,
-    at which point markers will no longer be limited to instances of :py:class:`~_pytest.mark.Mark`.
+    at which point markers will no longer be limited to instances of :py:class:`~pytest.Mark`.
 
 
 cache plugin integrated into the core

doc/en/historical-notes.rst

@@ -382,8 +382,6 @@ warnings: a WarningsRecorder instance. To view the recorded warnings, you can
 iterate over this instance, call ``len`` on it to get the number of recorded
 warnings, or index into it to get a particular recorded warning.
 
-.. currentmodule:: _pytest.warnings
-
 Full API: :class:`~_pytest.recwarn.WarningsRecorder`.
 
 .. _`warns use cases`:

doc/en/how-to/capture-warnings.rst

@@ -1271,7 +1271,7 @@ configured in multiple ways.
 Extending the previous example, we can flag the fixture to create two
 ``smtp_connection`` fixture instances which will cause all tests using the fixture
 to run twice.  The fixture function gets access to each parameter
-through the special :py:class:`request <FixtureRequest>` object:
+through the special :py:class:`request <pytest.FixtureRequest>` object:
 
 .. code-block:: python
 

doc/en/how-to/fixtures.rst

@@ -59,10 +59,6 @@ The remaining hook functions will not be called in this case.
 hook wrappers: executing around other hooks
 -------------------------------------------------
 
-.. currentmodule:: _pytest.core
-
-
-
 pytest plugins can implement hook wrappers which wrap the execution
 of other hook implementations.  A hook wrapper is a generator function
 which yields exactly once. When pytest invokes hooks it first executes
@@ -165,6 +161,7 @@ Here is the order of execution:
 It's possible to use ``tryfirst`` and ``trylast`` also on hook wrappers
 in which case it will influence the ordering of hook wrappers among each other.
 
+.. _`declaringhooks`:
 
 Declaring new hooks
 ------------------------
@@ -174,13 +171,11 @@ Declaring new hooks
     This is a quick overview on how to add new hooks and how they work in general, but a more complete
     overview can be found in `the pluggy documentation <https://pluggy.readthedocs.io/en/latest/>`__.
 
-.. currentmodule:: _pytest.hookspec
-
 Plugins and ``conftest.py`` files may declare new hooks that can then be
 implemented by other plugins in order to alter behaviour or interact with
 the new plugin:
 
-.. autofunction:: pytest_addhooks
+.. autofunction:: _pytest.hookspec.pytest_addhooks
     :noindex:
 
 Hooks are usually declared as do-nothing functions that contain only

doc/en/how-to/writing_hook_functions.rst

@@ -11,9 +11,6 @@ Fixtures reference
 .. seealso:: :ref:`about-fixtures`
 .. seealso:: :ref:`how-to-fixtures`
 
-
-.. currentmodule:: _pytest.python
-
 .. _`Dependency injection`: https://en.wikipedia.org/wiki/Dependency_injection
 
 
@@ -76,15 +73,13 @@ Built-in fixtures
         :class:`pathlib.Path` objects.
 
    :fixture:`tmpdir`
-        Provide a :class:`py.path.local` object to a temporary
+        Provide a `py.path.local <https://py.readthedocs.io/en/latest/path.html>`_ 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;
+        ``py.path.local`` objects;
         replaced by :fixture:`tmp_path_factory`.
 
 

doc/en/reference/fixtures.rst

@@ -612,10 +612,30 @@ Hooks
 
 **Tutorial**: :ref:`writing-plugins`
 
-.. currentmodule:: _pytest.hookspec
-
 Reference to all hooks which can be implemented by :ref:`conftest.py files <localplugin>` and :ref:`plugins <plugins>`.
 
+@pytest.hookimpl
+~~~~~~~~~~~~~~~~
+
+.. function:: pytest.hookimpl
+    :decorator:
+
+    pytest's decorator for marking functions as hook implementations.
+
+    See :ref:`writinghooks` and :func:`pluggy.HookimplMarker`.
+
+@pytest.hookspec
+~~~~~~~~~~~~~~~~
+
+.. function:: pytest.hookspec
+    :decorator:
+
+    pytest's decorator for marking functions as hook specifications.
+
+    See :ref:`declaringhooks` and :func:`pluggy.HookspecMarker`.
+
+.. currentmodule:: _pytest.hookspec
+
 Bootstrapping hooks
 ~~~~~~~~~~~~~~~~~~~
 

doc/en/reference/reference.rst

@@ -588,7 +588,7 @@ def writeorg(self, data: str) -> None:
 
     @final
     class CaptureResult(NamedTuple, Generic[AnyStr]):
-        """The result of :method:`CaptureFixture.readouterr`."""
+        """The result of :method:`caplog.readouterr() <pytest.CaptureFixture.readouterr>`."""
 
         out: AnyStr
         err: AnyStr
@@ -598,7 +598,7 @@ class CaptureResult(NamedTuple, Generic[AnyStr]):
     class CaptureResult(
         collections.namedtuple("CaptureResult", ["out", "err"]), Generic[AnyStr]
     ):
-        """The result of :method:`CaptureFixture.readouterr`."""
+        """The result of :method:`caplog.readouterr() <pytest.CaptureFixture.readouterr>`."""
 
         __slots__ = ()
 

src/_pytest/capture.py

@@ -98,7 +98,7 @@ def addoption(self, *opts: str, **attrs: Any) -> None:
         :param opts:
             Option names, can be short or long options.
         :param attrs:
-            Same attributes as the argparse library's :py:func:`add_argument()
+            Same attributes as the argparse library's :meth:`add_argument()
             <argparse.ArgumentParser.add_argument>` function accepts.
 
         After command line parsing, options are available on the pytest config
@@ -400,7 +400,7 @@ def addoption(self, *opts: str, **attrs: Any) -> None:
         :param opts:
             Option names, can be short or long options.
         :param attrs:
-            Same attributes as the argparse library's :py:func:`add_argument()
+            Same attributes as the argparse library's :meth:`add_argument()
             <argparse.ArgumentParser.add_argument>` function accepts.
         """
         conflict = set(opts).intersection(

src/_pytest/config/argparsing.py

@@ -96,8 +96,8 @@ def pytest_addoption(parser: "Parser", pluginmanager: "PytestPluginManager") ->
         <pytest.Parser.addini>`.
 
     :param pytest.PytestPluginManager pluginmanager:
-        The pytest plugin manager, which can be used to install :py:func:`hookspec`'s
-        or :py:func:`hookimpl`'s and allow one plugin to call another plugin's hooks
+        The pytest plugin manager, which can be used to install :py:func:`~pytest.hookspec`'s
+        or :py:func:`~pytest.hookimpl`'s and allow one plugin to call another plugin's hooks
         to change how command line options are added.
 
     Options can later be accessed through the

src/_pytest/hookspec.py

@@ -88,7 +88,6 @@ def chdir(self) -> None:
         return self._pytester.chdir()
 
     def finalize(self) -> None:
-        """See :meth:`Pytester._finalize`."""
         return self._pytester._finalize()
 
     def makefile(self, ext, *args, **kwargs) -> LEGACY_PATH:
@@ -269,7 +268,7 @@ def testdir(pytester: Pytester) -> Testdir:
 @final
 @dataclasses.dataclass
 class TempdirFactory:
-    """Backward compatibility wrapper that implements :class:`py.path.local`
+    """Backward compatibility wrapper that implements ``py.path.local``
     for :class:`TempPathFactory`.
 
     .. note::
@@ -288,11 +287,11 @@ def __init__(
         self._tmppath_factory = tmppath_factory
 
     def mktemp(self, basename: str, numbered: bool = True) -> LEGACY_PATH:
-        """Same as :meth:`TempPathFactory.mktemp`, but returns a :class:`py.path.local` object."""
+        """Same as :meth:`TempPathFactory.mktemp`, but returns a ``py.path.local`` object."""
         return legacy_path(self._tmppath_factory.mktemp(basename, numbered).resolve())
 
     def getbasetemp(self) -> LEGACY_PATH:
-        """Same as :meth:`TempPathFactory.getbasetemp`, but returns a :class:`py.path.local` object."""
+        """Same as :meth:`TempPathFactory.getbasetemp`, but returns a ``py.path.local`` object."""
         return legacy_path(self._tmppath_factory.getbasetemp().resolve())
 
 

src/_pytest/legacypath.py

@@ -522,7 +522,7 @@ def set_level(self, level: Union[int, str], logger: Optional[str] = None) -> Non
             The levels of the loggers changed by this function will be
             restored to their initial values at the end of the test.
 
-        Will enable the requested logging level if it was disabled via :meth:`logging.disable`.
+        Will enable the requested logging level if it was disabled via :func:`logging.disable`.
 
         :param level: The level.
         :param logger: The logger to update. If not given, the root logger.
@@ -546,7 +546,7 @@ def at_level(
         the end of the 'with' statement the level is restored to its original
         value.
 
-        Will enable the requested logging level if it was disabled via :meth:`logging.disable`.
+        Will enable the requested logging level if it was disabled via :func:`logging.disable`.
 
         :param level: The level.
         :param logger: The logger to update. If not given, the root logger.

src/_pytest/logging.py

@@ -1044,7 +1044,7 @@ def runitem(self, source: str) -> Any:
         The calling test instance (class containing the test method) must
         provide a ``.getrunner()`` method which should return a runner which
         can run the test protocol for a single item, e.g.
-        :py:func:`_pytest.runner.runtestprotocol`.
+        ``_pytest.runner.runtestprotocol``.
         """
         # used from runner functional tests
         item = self.getitem(source)
@@ -1395,7 +1395,7 @@ def run(
         :param stdin:
             Optional standard input.
 
-            - If it is :py:attr:`CLOSE_STDIN` (Default), then this method calls
+            - If it is ``CLOSE_STDIN`` (Default), then this method calls
               :py:class:`subprocess.Popen` with ``stdin=subprocess.PIPE``, and
               the standard input is closed immediately after the new command is
               started.

src/_pytest/pytester.py

@@ -825,8 +825,6 @@ def raises(  # noqa: F811
         When using :py:func:`pytest.raises` as a function, you can use:
         ``pytest.raises(Exc, func, match="passed on").match("my pattern")``.)
 
-    .. currentmodule:: _pytest._code
-
     Use ``pytest.raises`` as a context manager, which will capture the exception of the given
     type, or any of its subclasses::