Doc fixes (#6861)

doc/en/conf.py

@@ -343,7 +343,10 @@ texinfo_documents = [
 
 
 # Example configuration for intersphinx: refer to the Python standard library.
-intersphinx_mapping = {"python": ("https://docs.python.org/3", None)}
+intersphinx_mapping = {
+    "pluggy": ("https://pluggy.readthedocs.io/en/latest", None),
+    "python": ("https://docs.python.org/3", None),
+}
 
 
 def configure_logging(app: "sphinx.application.Sphinx") -> None:

doc/en/example/simple.rst

@@ -222,8 +222,10 @@ Or run it including the ``slow`` marked test:
 
     ============================ 2 passed in 0.12s =============================
 
+.. _`__tracebackhide__`:
+
 Writing well integrated assertion helpers
---------------------------------------------------
+-----------------------------------------
 
 .. regendoc:wipe
 

doc/en/reference.rst

@@ -881,13 +881,17 @@ TestReport
 
 .. autoclass:: _pytest.runner.TestReport()
     :members:
+    :show-inheritance:
     :inherited-members:
 
 _Result
 ~~~~~~~
 
+Result used within :ref:`hook wrappers <hookwrapper>`.
+
 .. autoclass:: pluggy.callers._Result
-    :members:
+.. automethod:: pluggy.callers._Result.get_result
+.. automethod:: pluggy.callers._Result.force_result
 
 Special Variables
 -----------------

doc/en/warnings.rst

@@ -418,19 +418,28 @@ features.
 The following warning types are used by pytest and are part of the public API:
 
 .. autoclass:: pytest.PytestWarning
+   :show-inheritance:
 
 .. autoclass:: pytest.PytestAssertRewriteWarning
+   :show-inheritance:
 
 .. autoclass:: pytest.PytestCacheWarning
+   :show-inheritance:
 
 .. autoclass:: pytest.PytestCollectionWarning
+   :show-inheritance:
 
 .. autoclass:: pytest.PytestConfigWarning
+   :show-inheritance:
 
 .. autoclass:: pytest.PytestDeprecationWarning
+   :show-inheritance:
 
 .. autoclass:: pytest.PytestExperimentalApiWarning
+   :show-inheritance:
 
 .. autoclass:: pytest.PytestUnhandledCoroutineWarning
+   :show-inheritance:
 
 .. autoclass:: pytest.PytestUnknownMarkWarning
+   :show-inheritance:

doc/en/writing_plugins.rst

@@ -513,6 +513,7 @@ call only executes until the first of N registered functions returns a
 non-None result which is then taken as result of the overall hook call.
 The remaining hook functions will not be called in this case.
 
+.. _`hookwrapper`:
 
 hookwrapper: executing around other hooks
 -------------------------------------------------
@@ -557,7 +558,8 @@ perform tracing or other side effects around the actual hook implementations.
 If the result of the underlying hook is a mutable object, they may modify
 that result but it's probably better to avoid it.
 
-For more information, consult the `pluggy documentation <http://pluggy.readthedocs.io/en/latest/#wrappers>`_.
+For more information, consult the
+:ref:`pluggy documentation about hookwrappers <pluggy:hookwrappers>`.
 
 
 Hook function ordering / call example

src/_pytest/config/__init__.py

@@ -731,26 +731,19 @@ class Config:
     """
     Access to configuration values, pluginmanager and plugin hooks.
 
-    :ivar PytestPluginManager pluginmanager: the plugin manager handles plugin registration and hook invocation.
-
-    :ivar argparse.Namespace option: access to command line option as attributes.
-
-    :ivar InvocationParams invocation_params:
+    :param PytestPluginManager pluginmanager:
 
+    :param InvocationParams invocation_params:
         Object containing the parameters regarding the ``pytest.main``
         invocation.
-
-        Contains the following read-only attributes:
-
-        * ``args``: tuple of command-line arguments as passed to ``pytest.main()``.
-        * ``plugins``: list of extra plugins, might be None.
-        * ``dir``: directory where ``pytest.main()`` was invoked from.
     """
 
     @attr.s(frozen=True)
     class InvocationParams:
         """Holds parameters passed during ``pytest.main()``
 
+        The object attributes are read-only.
+
         .. versionadded:: 5.1
 
         .. note::
@@ -762,10 +755,18 @@ class Config:
         """
 
         args = attr.ib(converter=tuple)
+        """tuple of command-line arguments as passed to ``pytest.main()``."""
         plugins = attr.ib()
+        """list of extra plugins, might be `None`."""
         dir = attr.ib(type=Path)
+        """directory where ``pytest.main()`` was invoked from."""
 
-    def __init__(self, pluginmanager, *, invocation_params=None) -> None:
+    def __init__(
+        self,
+        pluginmanager: PytestPluginManager,
+        *,
+        invocation_params: Optional[InvocationParams] = None
+    ) -> None:
         from .argparsing import Parser, FILE_OR_DIR
 
         if invocation_params is None:
@@ -774,6 +775,10 @@ class Config:
             )
 
         self.option = argparse.Namespace()
+        """access to command line option as attributes.
+
+          :type: argparse.Namespace"""
+
         self.invocation_params = invocation_params
 
         _a = FILE_OR_DIR
@@ -782,6 +787,10 @@ class Config:
             processopt=self._processopt,
         )
         self.pluginmanager = pluginmanager
+        """the plugin manager handles plugin registration and hook invocation.
+
+          :type: PytestPluginManager"""
+
         self.trace = self.pluginmanager.trace.root.get("config")
         self.hook = self.pluginmanager.hook
         self._inicache = {}  # type: Dict[str, Any]

src/_pytest/deprecated.py

@@ -5,7 +5,8 @@ that is planned to be removed in the next pytest release.
 Keeping it in a central location makes it easy to track what is deprecated and should
 be removed when the time comes.
 
-All constants defined in this module should be either PytestWarning instances or UnformattedWarning
+All constants defined in this module should be either instances of
+:class:`PytestWarning`, or :class:`UnformattedWarning`
 in case of warnings which need to format their messages.
 """
 from _pytest.warning_types import PytestDeprecationWarning

src/_pytest/pytester.py

@@ -395,19 +395,7 @@ rex_outcome = re.compile(r"(\d+) (\w+)")
 
 
 class RunResult:
-    """The result of running a command.
-
-    Attributes:
-
-    :ivar ret: the return value
-    :ivar outlines: list of lines captured from stdout
-    :ivar errlines: list of lines captured from stderr
-    :ivar stdout: :py:class:`LineMatcher` of stdout, use ``stdout.str()`` to
-       reconstruct stdout or the commonly used ``stdout.fnmatch_lines()``
-       method
-    :ivar stderr: :py:class:`LineMatcher` of stderr
-    :ivar duration: duration in seconds
-    """
+    """The result of running a command."""
 
     def __init__(
         self,
@@ -418,13 +406,23 @@ class RunResult:
     ) -> None:
         try:
             self.ret = pytest.ExitCode(ret)  # type: Union[int, ExitCode]
+            """the return value"""
         except ValueError:
             self.ret = ret
         self.outlines = outlines
+        """list of lines captured from stdout"""
         self.errlines = errlines
+        """list of lines captured from stderr"""
         self.stdout = LineMatcher(outlines)
+        """:class:`LineMatcher` of stdout.
+
+        Use e.g. :func:`stdout.str() <LineMatcher.str()>` to reconstruct stdout, or the commonly used
+        :func:`stdout.fnmatch_lines() <LineMatcher.fnmatch_lines()>` method.
+        """
         self.stderr = LineMatcher(errlines)
+        """:class:`LineMatcher` of stderr"""
         self.duration = duration
+        """duration in seconds"""
 
     def __repr__(self) -> str:
         return (

src/_pytest/reports.py

@@ -131,7 +131,7 @@ class BaseReport:
         """
         **Experimental**
 
-        Returns True if this report should be counted towards the totals shown at the end of the
+        ``True`` if this report should be counted towards the totals shown at the end of the
         test session: "1 passed, 1 failure, etc".
 
         .. note::

src/_pytest/warning_types.py

@@ -11,71 +11,46 @@ if TYPE_CHECKING:
 
 
 class PytestWarning(UserWarning):
-    """
-    Bases: :class:`UserWarning`.
-
-    Base class for all warnings emitted by pytest.
-    """
+    """Base class for all warnings emitted by pytest."""
 
     __module__ = "pytest"
 
 
 class PytestAssertRewriteWarning(PytestWarning):
-    """
-    Bases: :class:`PytestWarning`.
-
-    Warning emitted by the pytest assert rewrite module.
-    """
+    """Warning emitted by the pytest assert rewrite module."""
 
     __module__ = "pytest"
 
 
 class PytestCacheWarning(PytestWarning):
-    """
-    Bases: :class:`PytestWarning`.
-
-    Warning emitted by the cache plugin in various situations.
-    """
+    """Warning emitted by the cache plugin in various situations."""
 
     __module__ = "pytest"
 
 
 class PytestConfigWarning(PytestWarning):
-    """
-    Bases: :class:`PytestWarning`.
-
-    Warning emitted for configuration issues.
-    """
+    """Warning emitted for configuration issues."""
 
     __module__ = "pytest"
 
 
 class PytestCollectionWarning(PytestWarning):
-    """
-    Bases: :class:`PytestWarning`.
-
-    Warning emitted when pytest is not able to collect a file or symbol in a module.
-    """
+    """Warning emitted when pytest is not able to collect a file or symbol in a module."""
 
     __module__ = "pytest"
 
 
 class PytestDeprecationWarning(PytestWarning, DeprecationWarning):
-    """
-    Bases: :class:`pytest.PytestWarning`, :class:`DeprecationWarning`.
-
-    Warning class for features that will be removed in a future version.
-    """
+    """Warning class for features that will be removed in a future version."""
 
     __module__ = "pytest"
 
 
 class PytestExperimentalApiWarning(PytestWarning, FutureWarning):
-    """
-    Bases: :class:`pytest.PytestWarning`, :class:`FutureWarning`.
+    """Warning category used to denote experiments in pytest.
 
-    Warning category used to denote experiments in pytest. Use sparingly as the API might change or even be
-    removed completely in future version
+    Use sparingly as the API might change or even be removed completely in a
+    future version.
     """
 
     __module__ = "pytest"
@@ -90,22 +65,19 @@ class PytestExperimentalApiWarning(PytestWarning, FutureWarning):
 
 
 class PytestUnhandledCoroutineWarning(PytestWarning):
-    """
-    Bases: :class:`PytestWarning`.
+    """Warning emitted for an unhandled coroutine.
 
-    Warning emitted when pytest encounters a test function which is a coroutine,
-    but it was not handled by any async-aware plugin. Coroutine test functions
-    are not natively supported.
+    A coroutine was encountered when collecting test functions, but was not
+    handled by any async-aware plugin.
+    Coroutine test functions are not natively supported.
     """
 
     __module__ = "pytest"
 
 
 class PytestUnknownMarkWarning(PytestWarning):
-    """
-    Bases: :class:`PytestWarning`.
+    """Warning emitted on use of unknown markers.
 
-    Warning emitted on use of unknown markers.
     See https://docs.pytest.org/en/latest/mark.html for details.
     """
 
@@ -117,9 +89,10 @@ _W = TypeVar("_W", bound=PytestWarning)
 
 @attr.s
 class UnformattedWarning(Generic[_W]):
-    """Used to hold warnings that need to format their message at runtime, as opposed to a direct message.
+    """A warning meant to be formatted during runtime.
 
-    Using this class avoids to keep all the warning types and messages in this module, avoiding misuse.
+    This is used to hold warnings that need to format their message at runtime,
+    as opposed to a direct message.
     """
 
     category = attr.ib(type="Type[_W]")