Merge pull request #11684 from bluetech/docs-nitpicky

docs: enable Sphinx nitpicky mode

doc/en/changelog.rst

@@ -1344,7 +1344,7 @@ Features
 
   This is part of the movement to use :class:`pathlib.Path` objects internally, in order to remove the dependency to ``py`` in the future.
 
-  Internally, the old :class:`~pytest.Testdir` is now a thin wrapper around :class:`~pytest.Pytester`, preserving the old interface.
+  Internally, the old ``pytest.Testdir`` is now a thin wrapper around :class:`~pytest.Pytester`, preserving the old interface.
 
 
 - :issue:`7695`: A new hook was added, `pytest_markeval_namespace` which should return a dictionary.
@@ -1592,7 +1592,7 @@ Improvements
 
 
 - :issue:`7685`: Added two new attributes :attr:`rootpath <pytest.Config.rootpath>` and :attr:`inipath <pytest.Config.inipath>` to :class:`~pytest.Config`.
-  These attributes are :class:`pathlib.Path` versions of the existing :attr:`rootdir <pytest.Config.rootdir>` and :attr:`inifile <pytest.Config.inifile>` attributes,
+  These attributes are :class:`pathlib.Path` versions of the existing ``rootdir`` and ``inifile`` attributes,
   and should be preferred over them when possible.
 
 
@@ -2139,7 +2139,7 @@ Bug Fixes
   parameter when Python is called with the ``-bb`` flag.
 
 
-- :issue:`7143`: Fix :meth:`pytest.File.from_parent` so it forwards extra keyword arguments to the constructor.
+- :issue:`7143`: Fix :meth:`pytest.File.from_parent <_pytest.nodes.Node.from_parent>` so it forwards extra keyword arguments to the constructor.
 
 
 - :issue:`7145`: Classes with broken ``__getattribute__`` methods are displayed correctly during failures.
@@ -2458,7 +2458,7 @@ Bug Fixes
 - :issue:`6597`: Fix node ids which contain a parametrized empty-string variable.
 
 
-- :issue:`6646`: Assertion rewriting hooks are (re)stored for the current item, which fixes them being still used after e.g. pytester's :func:`testdir.runpytest <pytest.Testdir.runpytest>` etc.
+- :issue:`6646`: Assertion rewriting hooks are (re)stored for the current item, which fixes them being still used after e.g. pytester's ``testdir.runpytest`` etc.
 
 
 - :issue:`6660`: :py:func:`pytest.exit` is handled when emitted from the :hook:`pytest_sessionfinish` hook.  This includes quitting from a debugger.

doc/en/conf.py

@@ -169,6 +169,50 @@ extlinks = {
 }
 
 
+nitpicky = True
+nitpick_ignore = [
+    # TODO (fix in pluggy?)
+    ("py:class", "HookCaller"),
+    ("py:class", "HookspecMarker"),
+    ("py:exc", "PluginValidationError"),
+    # Might want to expose/TODO (https://github.com/pytest-dev/pytest/issues/7469)
+    ("py:class", "ExceptionRepr"),
+    ("py:class", "Exit"),
+    ("py:class", "SubRequest"),
+    ("py:class", "SubRequest"),
+    ("py:class", "TerminalReporter"),
+    ("py:class", "_pytest._code.code.TerminalRepr"),
+    ("py:class", "_pytest.fixtures.FixtureFunctionMarker"),
+    ("py:class", "_pytest.logging.LogCaptureHandler"),
+    ("py:class", "_pytest.mark.structures.ParameterSet"),
+    # Intentionally undocumented/private
+    ("py:class", "_pytest._code.code.Traceback"),
+    ("py:class", "_pytest._py.path.LocalPath"),
+    ("py:class", "_pytest.capture.CaptureResult"),
+    ("py:class", "_pytest.compat.NotSetType"),
+    ("py:class", "_pytest.python.PyCollector"),
+    ("py:class", "_pytest.python.PyobjMixin"),
+    ("py:class", "_pytest.python_api.RaisesContext"),
+    ("py:class", "_pytest.recwarn.WarningsChecker"),
+    ("py:class", "_pytest.reports.BaseReport"),
+    # Undocumented third parties
+    ("py:class", "_tracing.TagTracerSub"),
+    ("py:class", "warnings.WarningMessage"),
+    # Undocumented type aliases
+    ("py:class", "LEGACY_PATH"),
+    ("py:class", "_PluggyPlugin"),
+    # TypeVars
+    ("py:class", "_pytest._code.code.E"),
+    ("py:class", "_pytest.fixtures.FixtureFunction"),
+    ("py:class", "_pytest.nodes._NodeType"),
+    ("py:class", "_pytest.python_api.E"),
+    ("py:class", "_pytest.recwarn.T"),
+    ("py:class", "_pytest.runner.TResult"),
+    ("py:obj", "_pytest.fixtures.FixtureValue"),
+    ("py:obj", "_pytest.stash.T"),
+]
+
+
 # -- Options for HTML output ---------------------------------------------------
 
 sys.path.append(os.path.abspath("_themes"))

doc/en/example/simple.rst

@@ -168,7 +168,7 @@ Now we'll get feedback on a bad argument:
 
 
 If you need to provide more detailed error messages, you can use the
-``type`` parameter and raise ``pytest.UsageError``:
+``type`` parameter and raise :exc:`pytest.UsageError`:
 
 .. code-block:: python
 

doc/en/funcarg_compare.rst

@@ -44,7 +44,7 @@ There are several limitations and difficulties with this approach:
 
 2. parametrizing the "db" resource is not straight forward:
    you need to apply a "parametrize" decorator or implement a
-   :py:func:`~hookspec.pytest_generate_tests` hook
+   :hook:`pytest_generate_tests` hook
    calling :py:func:`~pytest.Metafunc.parametrize` which
    performs parametrization at the places where the resource
    is used.  Moreover, you need to modify the factory to use an
@@ -92,7 +92,7 @@ Direct parametrization of funcarg resource factories
 
 Previously, funcarg factories could not directly cause parametrization.
 You needed to specify a ``@parametrize`` decorator on your test function
-or implement a ``pytest_generate_tests`` hook to perform
+or implement a :hook:`pytest_generate_tests` hook to perform
 parametrization, i.e. calling a test multiple times with different value
 sets.  pytest-2.3 introduces a decorator for use on the factory itself:
 

doc/en/reference/reference.rst

@@ -1158,7 +1158,10 @@ When set (regardless of value), pytest will use color in terminal output.
 Exceptions
 ----------
 
-.. autoclass:: pytest.UsageError()
+.. autoexception:: pytest.UsageError()
+    :show-inheritance:
+
+.. autoexception:: pytest.FixtureLookupError()
     :show-inheritance:
 
 .. _`warnings ref`:

src/_pytest/config/__init__.py

@@ -449,6 +449,7 @@ class PytestPluginManager(PluginManager):
     def parse_hookimpl_opts(
         self, plugin: _PluggyPlugin, name: str
     ) -> Optional[HookimplOpts]:
+        """:meta private:"""
         # pytest hooks are always prefixed with "pytest_",
         # so we avoid accessing possibly non-readable attributes
         # (see issue #1073).
@@ -472,6 +473,7 @@ class PytestPluginManager(PluginManager):
         )
 
     def parse_hookspec_opts(self, module_or_class, name: str) -> Optional[HookspecOpts]:
+        """:meta private:"""
         opts = super().parse_hookspec_opts(module_or_class, name)
         if opts is None:
             method = getattr(module_or_class, name)

src/_pytest/hookspec.py

@@ -55,7 +55,7 @@ hookspec = HookspecMarker("pytest")
 @hookspec(historic=True)
 def pytest_addhooks(pluginmanager: "PytestPluginManager") -> None:
     """Called at plugin registration time to allow adding new hooks via a call to
-    ``pluginmanager.add_hookspecs(module_or_class, prefix)``.
+    :func:`pluginmanager.add_hookspecs(module_or_class, prefix) <pytest.PytestPluginManager.add_hookspecs>`.
 
     :param pytest.PytestPluginManager pluginmanager: The pytest plugin manager.
 
@@ -858,8 +858,8 @@ def pytest_warning_recorded(
     """Process a warning captured by the internal pytest warnings plugin.
 
     :param warning_message:
-        The captured warning. This is the same object produced by :py:func:`warnings.catch_warnings`, and contains
-        the same attributes as the parameters of :py:func:`warnings.showwarning`.
+        The captured warning. This is the same object produced by :class:`warnings.catch_warnings`,
+        and contains the same attributes as the parameters of :py:func:`warnings.showwarning`.
 
     :param when:
         Indicates when the warning was captured. Possible values:
@@ -940,10 +940,10 @@ def pytest_exception_interact(
     interactively handled.
 
     May be called during collection (see :hook:`pytest_make_collect_report`),
-    in which case ``report`` is a :class:`CollectReport`.
+    in which case ``report`` is a :class:`~pytest.CollectReport`.
 
     May be called during runtest of an item (see :hook:`pytest_runtest_protocol`),
-    in which case ``report`` is a :class:`TestReport`.
+    in which case ``report`` is a :class:`~pytest.TestReport`.
 
     This hook is not called if the exception that was raised is an internal
     exception like ``skip.Exception``.

src/_pytest/nodes.py

@@ -1,5 +1,6 @@
 import abc
 import os
+import pathlib
 import warnings
 from functools import cached_property
 from inspect import signature
@@ -177,8 +178,8 @@ class Node(abc.ABC, metaclass=NodeMeta):
     # Implemented in the legacypath plugin.
     #: A ``LEGACY_PATH`` copy of the :attr:`path` attribute. Intended for usage
     #: for methods not migrated to ``pathlib.Path`` yet, such as
-    #: :meth:`Item.reportinfo`. Will be deprecated in a future release, prefer
-    #: using :attr:`path` instead.
+    #: :meth:`Item.reportinfo <pytest.Item.reportinfo>`. Will be deprecated in
+    #: a future release, prefer using :attr:`path` instead.
     fspath: LEGACY_PATH
 
     # Use __slots__ to make attribute access faster.
@@ -229,7 +230,7 @@ class Node(abc.ABC, metaclass=NodeMeta):
         if path is None and fspath is None:
             path = getattr(parent, "path", None)
         #: Filesystem path where this node was collected from (can be None).
-        self.path: Path = _imply_path(type(self), path, fspath=fspath)
+        self.path: pathlib.Path = _imply_path(type(self), path, fspath=fspath)
 
         # The explicit annotation is to avoid publicly exposing NodeKeywords.
         #: Keywords/markers collected from all scopes.

src/_pytest/python_api.py

@@ -30,15 +30,6 @@ if TYPE_CHECKING:
     from numpy import ndarray
 
 
-def _non_numeric_type_error(value, at: Optional[str]) -> TypeError:
-    at_str = f" at {at}" if at else ""
-    return TypeError(
-        "cannot make approximate comparisons to non-numeric values: {!r} {}".format(
-            value, at_str
-        )
-    )
-
-
 def _compare_approx(
     full_object: object,
     message_data: Sequence[Tuple[str, str, str]],
@@ -806,23 +797,23 @@ def raises(  # noqa: F811
 ) -> Union["RaisesContext[E]", _pytest._code.ExceptionInfo[E]]:
     r"""Assert that a code block/function call raises an exception type, or one of its subclasses.
 
-    :param typing.Type[E] | typing.Tuple[typing.Type[E], ...] expected_exception:
+    :param expected_exception:
         The expected exception type, or a tuple if one of multiple possible
         exception types are expected. Note that subclasses of the passed exceptions
         will also match.
 
-    :kwparam str | typing.Pattern[str] | None match:
+    :kwparam str | re.Pattern[str] | None match:
         If specified, a string containing a regular expression,
         or a regular expression object, that is tested against the string
-        representation of the exception and its `PEP-678 <https://peps.python.org/pep-0678/>` `__notes__`
+        representation of the exception and its :pep:`678` `__notes__`
         using :func:`re.search`.
 
         To match a literal string that may contain :ref:`special characters
         <re-syntax>`, the pattern can first be escaped with :func:`re.escape`.
 
-        (This is only used when :py:func:`pytest.raises` is used as a context manager,
+        (This is only used when ``pytest.raises`` is used as a context manager,
         and passed through to the function otherwise.
-        When using :py:func:`pytest.raises` as a function, you can use:
+        When using ``pytest.raises`` as a function, you can use:
         ``pytest.raises(Exc, func, match="passed on").match("my pattern")``.)
 
     Use ``pytest.raises`` as a context manager, which will capture the exception of the given