Merge pull request #9248 from bluetech/sphinx4

doc: support sphinx 5

Author: bluetech

doc/en/conf.py

@@ -38,6 +38,7 @@
 
 autodoc_member_order = "bysource"
 autodoc_typehints = "description"
+autodoc_typehints_description_target = "documented"
 todo_include_todos = 1
 
 latex_engine = "lualatex"
@@ -162,11 +163,11 @@
 
 _repo = "https://github.com/pytest-dev/pytest"
 extlinks = {
-    "bpo": ("https://bugs.python.org/issue%s", "bpo-"),
-    "pypi": ("https://pypi.org/project/%s/", ""),
-    "issue": (f"{_repo}/issues/%s", "issue #"),
-    "pull": (f"{_repo}/pull/%s", "pull request #"),
-    "user": ("https://github.com/%s", "@"),
+    "bpo": ("https://bugs.python.org/issue%s", "bpo-%s"),
+    "pypi": ("https://pypi.org/project/%s/", "%s"),
+    "issue": (f"{_repo}/issues/%s", "issue #%s"),
+    "pull": (f"{_repo}/pull/%s", "pull request #%s"),
+    "user": ("https://github.com/%s", "@%s"),
 }
 
 
@@ -419,8 +420,6 @@ def filter(self, record: logging.LogRecord) -> bool:
 
 
 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",

doc/en/reference/customize.rst

@@ -90,7 +90,7 @@ and can also be used to hold pytest configuration if they have a ``[pytest]`` se
 setup.cfg
 ~~~~~~~~~
 
-``setup.cfg`` files are general purpose configuration files, used originally by :doc:`distutils <distutils/configfile>`, and can also be used to hold pytest configuration
+``setup.cfg`` files are general purpose configuration files, used originally by :doc:`distutils <python:distutils/configfile>`, and can also be used to hold pytest configuration
 if they have a ``[tool:pytest]`` section.
 
 .. code-block:: ini

doc/en/reference/reference.rst

@@ -102,7 +102,7 @@ pytest.deprecated_call
 
 **Tutorial**: :ref:`ensuring_function_triggers`
 
-.. autofunction:: pytest.deprecated_call()
+.. autofunction:: pytest.deprecated_call([match])
     :with:
 
 pytest.register_assert_rewrite
@@ -529,6 +529,7 @@ New code should avoid using :fixture:`testdir` in favor of :fixture:`pytester`.
 
 .. autoclass:: pytest.Testdir()
     :members:
+    :noindex: TimeoutExpired
 
 
 .. fixture:: recwarn

doc/en/requirements.txt

@@ -2,9 +2,6 @@ pallets-sphinx-themes
 pluggy>=1.0
 pygments-pytest>=2.2.0
 sphinx-removed-in>=0.2.0
-sphinx>=3.1,<4
+sphinx>=5,<6
 sphinxcontrib-trio
 sphinxcontrib-svg2pdfconverter
-
-# XXX: sphinx<4 is broken with latest jinja2
-jinja2<3.1

src/_pytest/assertion/__init__.py

@@ -53,7 +53,7 @@ def register_assert_rewrite(*names: str) -> None:
     actually imported, usually in your __init__.py if you are a plugin
     using a package.
 
-    :raises TypeError: If the given module names are not strings.
+    :param names: The module names to register.
     """
     for name in names:
         if not isinstance(name, str):

src/_pytest/compat.py

@@ -20,6 +20,16 @@
 import attr
 import py
 
+# fmt: off
+# Workaround for https://github.com/sphinx-doc/sphinx/issues/10351.
+# If `overload` is imported from `compat` instead of from `typing`,
+# Sphinx doesn't recognize it as `overload` and the API docs for
+# overloaded functions look good again. But type checkers handle
+# it fine.
+# fmt: on
+if True:
+    from typing import overload as overload
+
 if TYPE_CHECKING:
     from typing_extensions import Final
 
@@ -345,7 +355,6 @@ def final(f):
 if sys.version_info >= (3, 8):
     from functools import cached_property as cached_property
 else:
-    from typing import overload
     from typing import Type
 
     class cached_property(Generic[_S, _T]):

src/_pytest/config/argparsing.py

@@ -66,14 +66,15 @@ def getgroup(
     ) -> "OptionGroup":
         """Get (or create) a named option Group.
 
-        :name: Name of the option group.
-        :description: Long description for --help output.
-        :after: Name of another group, used for ordering --help output.
+        :param name: Name of the option group.
+        :param description: Long description for --help output.
+        :param after: Name of another group, used for ordering --help output.
+        :returns: The option group.
 
         The returned group object has an ``addoption`` method with the same
         signature as :func:`parser.addoption <pytest.Parser.addoption>` but
         will be shown in the respective group in the output of
-        ``pytest. --help``.
+        ``pytest --help``.
         """
         for group in self._groups:
             if group.name == name:
@@ -89,10 +90,11 @@ def getgroup(
     def addoption(self, *opts: str, **attrs: Any) -> None:
         """Register a command line option.
 
-        :opts: Option names, can be short or long options.
-        :attrs: Same attributes which the ``add_argument()`` function of the
-           `argparse library <https://docs.python.org/library/argparse.html>`_
-           accepts.
+        :param opts:
+            Option names, can be short or long options.
+        :param attrs:
+            Same attributes as the argparse library's :py:func:`add_argument()
+            <argparse.ArgumentParser.add_argument>` function accepts.
 
         After command line parsing, options are available on the pytest config
         object via ``config.option.NAME`` where ``NAME`` is usually set
@@ -148,16 +150,24 @@ def parse_known_args(
         args: Sequence[Union[str, "os.PathLike[str]"]],
         namespace: Optional[argparse.Namespace] = None,
     ) -> argparse.Namespace:
-        """Parse and return a namespace object with known arguments at this point."""
+        """Parse the known arguments at this point.
+
+        :returns: An argparse namespace object.
+        """
         return self.parse_known_and_unknown_args(args, namespace=namespace)[0]
 
     def parse_known_and_unknown_args(
         self,
         args: Sequence[Union[str, "os.PathLike[str]"]],
         namespace: Optional[argparse.Namespace] = None,
     ) -> Tuple[argparse.Namespace, List[str]]:
-        """Parse and return a namespace object with known arguments, and
-        the remaining arguments unknown at this point."""
+        """Parse the known arguments at this point, and also return the
+        remaining unknown arguments.
+
+        :returns:
+            A tuple containing an argparse namespace object for the known
+            arguments, and a list of the unknown arguments.
+        """
         optparser = self._getparser()
         strargs = [os.fspath(x) for x in args]
         return optparser.parse_known_args(strargs, namespace=namespace)
@@ -173,9 +183,9 @@ def addini(
     ) -> None:
         """Register an ini-file option.
 
-        :name:
+        :param name:
             Name of the ini-variable.
-        :type:
+        :param type:
             Type of the variable. Can be:
 
                 * ``string``: a string
@@ -189,7 +199,7 @@ def addini(
                 The ``paths`` variable type.
 
             Defaults to ``string`` if ``None`` or not passed.
-        :default:
+        :param default:
             Default value if no ini-file option exists but is queried.
 
         The value of ini-variables can be retrieved via a call to
@@ -354,24 +364,30 @@ def __init__(
         self.options: List[Argument] = []
         self.parser = parser
 
-    def addoption(self, *optnames: str, **attrs: Any) -> None:
+    def addoption(self, *opts: str, **attrs: Any) -> None:
         """Add an option to this group.
 
         If a shortened version of a long option is specified, it will
         be suppressed in the help. ``addoption('--twowords', '--two-words')``
         results in help showing ``--two-words`` only, but ``--twowords`` gets
         accepted **and** the automatic destination is in ``args.twowords``.
+
+        :param opts:
+            Option names, can be short or long options.
+        :param attrs:
+            Same attributes as the argparse library's :py:func:`add_argument()
+            <argparse.ArgumentParser.add_argument>` function accepts.
         """
-        conflict = set(optnames).intersection(
+        conflict = set(opts).intersection(
             name for opt in self.options for name in opt.names()
         )
         if conflict:
             raise ValueError("option names %s already added" % conflict)
-        option = Argument(*optnames, **attrs)
+        option = Argument(*opts, **attrs)
         self._addoption_instance(option, shortupper=False)
 
-    def _addoption(self, *optnames: str, **attrs: Any) -> None:
-        option = Argument(*optnames, **attrs)
+    def _addoption(self, *opts: str, **attrs: Any) -> None:
+        option = Argument(*opts, **attrs)
         self._addoption_instance(option, shortupper=True)
 
     def _addoption_instance(self, option: "Argument", shortupper: bool = False) -> None:

src/_pytest/fixtures.py

@@ -20,7 +20,6 @@
 from typing import MutableMapping
 from typing import NoReturn
 from typing import Optional
-from typing import overload
 from typing import Sequence
 from typing import Set
 from typing import Tuple
@@ -48,6 +47,7 @@
 from _pytest.compat import getlocation
 from _pytest.compat import is_generator
 from _pytest.compat import NOTSET
+from _pytest.compat import overload
 from _pytest.compat import safe_getattr
 from _pytest.config import _PluggyPlugin
 from _pytest.config import Config
@@ -513,8 +513,8 @@ def session(self) -> "Session":
         return self._pyfuncitem.session  # type: ignore[no-any-return]
 
     def addfinalizer(self, finalizer: Callable[[], object]) -> None:
-        """Add finalizer/teardown function to be called after the last test
-        within the requesting test context finished execution."""
+        """Add finalizer/teardown function to be called without arguments after
+        the last test within the requesting test context finished execution."""
         # XXX usually this method is shadowed by fixturedef specific ones.
         self._addfinalizer(finalizer, scope=self.scope)
 
@@ -529,13 +529,16 @@ def applymarker(self, marker: Union[str, MarkDecorator]) -> None:
         on all function invocations.
 
         :param marker:
-            A :class:`pytest.MarkDecorator` object created by a call
-            to ``pytest.mark.NAME(...)``.
+            An object created by a call to ``pytest.mark.NAME(...)``.
         """
         self.node.add_marker(marker)
 
     def raiseerror(self, msg: Optional[str]) -> NoReturn:
-        """Raise a FixtureLookupError with the given message."""
+        """Raise a FixtureLookupError exception.
+
+        :param msg:
+            An optional custom error message.
+        """
         raise self._fixturemanager.FixtureLookupError(None, self, msg)
 
     def _fillfixtures(self) -> None:
@@ -557,6 +560,8 @@ def getfixturevalue(self, argname: str) -> Any:
         phase, but during the test teardown phase a fixture's value may not
         be available.
 
+        :param argname:
+            The fixture name.
         :raises pytest.FixtureLookupError:
             If the given fixture could not be found.
         """
@@ -768,8 +773,8 @@ def __repr__(self) -> str:
         return f"<SubRequest {self.fixturename!r} for {self._pyfuncitem!r}>"
 
     def addfinalizer(self, finalizer: Callable[[], object]) -> None:
-        """Add finalizer/teardown function to be called after the last test
-        within the requesting test context finished execution."""
+        """Add finalizer/teardown function to be called without arguments after
+        the last test within the requesting test context finished execution."""
         self._fixturedef.addfinalizer(finalizer)
 
     def _schedule_finalizers(
@@ -1226,7 +1231,7 @@ def fixture(
 
 
 @overload
-def fixture(
+def fixture(  # noqa: F811
     fixture_function: None = ...,
     *,
     scope: "Union[_ScopeName, Callable[[str, Config], _ScopeName]]" = ...,
@@ -1240,7 +1245,7 @@ def fixture(
     ...
 
 
-def fixture(
+def fixture(  # noqa: F811
     fixture_function: Optional[FixtureFunction] = None,
     *,
     scope: "Union[_ScopeName, Callable[[str, Config], _ScopeName]]" = "function",