doc: workaround for ugly API docs for overloaded functions with new S…

…phinx

New Sphinx added support for overloads and always displays them all with
full type annotations etc. This regresses the API reference for
overloaded functions like `fixture()`, `warns()`, `raises()` and friends
to become impossible to read.

I tried various workarounds but none worked except this one.

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/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
@@ -1231,7 +1231,7 @@ def fixture(
 
 
 @overload
-def fixture(
+def fixture(  # noqa: F811
     fixture_function: None = ...,
     *,
     scope: "Union[_ScopeName, Callable[[str, Config], _ScopeName]]" = ...,
@@ -1245,7 +1245,7 @@ def fixture(
     ...
 
 
-def fixture(
+def fixture(  # noqa: F811
     fixture_function: Optional[FixtureFunction] = None,
     *,
     scope: "Union[_ScopeName, Callable[[str, Config], _ScopeName]]" = "function",

src/_pytest/main.py

@@ -12,7 +12,6 @@
 from typing import Iterator
 from typing import List
 from typing import Optional
-from typing import overload
 from typing import Sequence
 from typing import Set
 from typing import Tuple
@@ -25,6 +24,7 @@
 import _pytest._code
 from _pytest import nodes
 from _pytest.compat import final
+from _pytest.compat import overload
 from _pytest.config import Config
 from _pytest.config import directory_arg
 from _pytest.config import ExitCode
@@ -597,12 +597,12 @@ def perform_collect(
         ...
 
     @overload
-    def perform_collect(
+    def perform_collect(  # noqa: F811
         self, args: Optional[Sequence[str]] = ..., genitems: bool = ...
     ) -> Sequence[Union[nodes.Item, nodes.Collector]]:
         ...
 
-    def perform_collect(
+    def perform_collect(  # noqa: F811
         self, args: Optional[Sequence[str]] = None, genitems: bool = True
     ) -> Sequence[Union[nodes.Item, nodes.Collector]]:
         """Perform the collection phase for this session.

src/_pytest/python_api.py

@@ -12,7 +12,6 @@
 from typing import List
 from typing import Mapping
 from typing import Optional
-from typing import overload
 from typing import Pattern
 from typing import Sequence
 from typing import Tuple
@@ -28,6 +27,7 @@
 import _pytest._code
 from _pytest.compat import final
 from _pytest.compat import STRING_TYPES
+from _pytest.compat import overload
 from _pytest.outcomes import fail
 
 
@@ -786,7 +786,7 @@ def raises(
 
 
 @overload
-def raises(
+def raises(  # noqa: F811
     expected_exception: Union[Type[E], Tuple[Type[E], ...]],
     func: Callable[..., Any],
     *args: Any,
@@ -795,7 +795,7 @@ def raises(
     ...
 
 
-def raises(
+def raises(  # noqa: F811
     expected_exception: Union[Type[E], Tuple[Type[E], ...]], *args: Any, **kwargs: Any
 ) -> Union["RaisesContext[E]", _pytest._code.ExceptionInfo[E]]:
     r"""Assert that a code block/function call raises an exception.

src/_pytest/recwarn.py

@@ -9,14 +9,14 @@
 from typing import Iterator
 from typing import List
 from typing import Optional
-from typing import overload
 from typing import Pattern
 from typing import Tuple
 from typing import Type
 from typing import TypeVar
 from typing import Union
 
 from _pytest.compat import final
+from _pytest.compat import overload
 from _pytest.deprecated import check_ispytest
 from _pytest.deprecated import WARNS_NONE_ARG
 from _pytest.fixtures import fixture
@@ -47,11 +47,13 @@ def deprecated_call(
 
 
 @overload
-def deprecated_call(func: Callable[..., T], *args: Any, **kwargs: Any) -> T:
+def deprecated_call(  # noqa: F811
+    func: Callable[..., T], *args: Any, **kwargs: Any
+) -> T:
     ...
 
 
-def deprecated_call(
+def deprecated_call(  # noqa: F811
     func: Optional[Callable[..., Any]] = None, *args: Any, **kwargs: Any
 ) -> Union["WarningsRecorder", Any]:
     """Assert that code produces a ``DeprecationWarning`` or ``PendingDeprecationWarning``.
@@ -93,7 +95,7 @@ def warns(
 
 
 @overload
-def warns(
+def warns(  # noqa: F811
     expected_warning: Union[Type[Warning], Tuple[Type[Warning], ...]],
     func: Callable[..., T],
     *args: Any,
@@ -102,7 +104,7 @@ def warns(
     ...
 
 
-def warns(
+def warns(  # noqa: F811
     expected_warning: Union[Type[Warning], Tuple[Type[Warning], ...]] = Warning,
     *args: Any,
     match: Optional[Union[str, Pattern[str]]] = None,