Use Sphinx 9 class interface (#589)

Author: gaborbernat

src/sphinx_autodoc_typehints/attributes_patch.py

@@ -7,9 +7,7 @@
 from unittest.mock import patch
 
 import sphinx.domains.python
-import sphinx.ext.autodoc
 from sphinx.domains.python import PyAttribute
-from sphinx.ext.autodoc import AttributeDocumenter
 
 from ._parser import parse
 
@@ -21,45 +19,16 @@
 # Defensively check for the things we want to patch
 _parse_annotation = getattr(sphinx.domains.python, "_parse_annotation", None)
 
-# We want to patch:
-# * sphinx.ext.autodoc.stringify_typehint (in sphinx < 6.1)
-# * sphinx.ext.autodoc.stringify_annotation (in sphinx >= 6.1)
-STRINGIFY_PATCH_TARGET = ""
-for target in ["stringify_typehint", "stringify_annotation"]:
-    if hasattr(sphinx.ext.autodoc, target):
-        STRINGIFY_PATCH_TARGET = f"sphinx.ext.autodoc.{target}"
-        break
-
-# If we didn't locate both patch targets, we will just do nothing.
-OKAY_TO_PATCH = bool(_parse_annotation and STRINGIFY_PATCH_TARGET)
+# If we didn't locate the patch target, we will just do nothing.
+OKAY_TO_PATCH = bool(_parse_annotation)
 
 # A label we inject to the type string so we know not to try to treat it as a
 # type annotation
 TYPE_IS_RST_LABEL = "--is-rst--"
 
-
-orig_add_directive_header = AttributeDocumenter.add_directive_header
 orig_handle_signature = PyAttribute.handle_signature
 
 
-def _stringify_annotation(app: Sphinx, annotation: Any, *args: Any, short_literals: bool = False, **kwargs: Any) -> str:  # noqa: ARG001
-    # Format the annotation with sphinx-autodoc-typehints and inject our magic prefix to tell our patched
-    # PyAttribute.handle_signature to treat it as rst.
-    from . import format_annotation  # noqa: PLC0415
-
-    return TYPE_IS_RST_LABEL + format_annotation(annotation, app.config, short_literals=short_literals)
-
-
-def patch_attribute_documenter(app: Sphinx) -> None:
-    """Instead of using stringify_typehint in `AttributeDocumenter.add_directive_header`, use `format_annotation`."""
-
-    def add_directive_header(*args: Any, **kwargs: Any) -> Any:
-        with patch(STRINGIFY_PATCH_TARGET, partial(_stringify_annotation, app)):
-            return orig_add_directive_header(*args, **kwargs)
-
-    AttributeDocumenter.add_directive_header = add_directive_header  # type:ignore[method-assign]
-
-
 def rst_to_docutils(settings: Values, rst: str) -> Any:
     """Convert rst to a sequence of docutils nodes."""
     doc = parse(rst, settings)
@@ -84,12 +53,11 @@ def patched_handle_signature(self: PyAttribute, sig: str, signode: desc_signatur
         return orig_handle_signature(self, sig, signode)
 
 
-def patch_attribute_handling(app: Sphinx) -> None:
-    """Use format_signature to format class attribute type annotations."""
+def patch_attribute_handling(app: Sphinx) -> None:  # noqa: ARG001
+    """Patch PyAttribute.handle_signature to format class attribute type annotations."""
     if not OKAY_TO_PATCH:
         return
     PyAttribute.handle_signature = patched_handle_signature  # type:ignore[method-assign]
-    patch_attribute_documenter(app)
 
 
 __all__ = ["patch_attribute_handling"]

src/sphinx_autodoc_typehints/patches.py

@@ -17,26 +17,6 @@
     from sphinx.ext.autodoc import Options
 
 
-@lru_cache  # A cute way to make sure the function only runs once.
-def fix_autodoc_typehints_for_overloaded_methods() -> None:
-    """
-    sphinx-autodoc-typehints responds to the "autodoc-process-signature" event to remove types from the signature line.
-
-    Normally, `FunctionDocumenter.format_signature` and `MethodDocumenter.format_signature` call
-    `super().format_signature` which ends up going to `Documenter.format_signature`, and this last method emits the
-    `autodoc-process-signature` event. However, if there are overloads, `FunctionDocumenter.format_signature` does
-    something else and the event never occurs.
-
-    We delete the format_signature methods to force using the parent implementation, which emits the event.
-
-    See https://github.com/tox-dev/sphinx-autodoc-typehints/issues/296
-    """
-    from sphinx.ext.autodoc import FunctionDocumenter, MethodDocumenter  # noqa: PLC0415
-
-    # Delete the format_signature methods that add overloads
-    # This forces everything to use Documenter.format_signature which emits the event
-    del FunctionDocumenter.format_signature
-    del MethodDocumenter.format_signature
 
 
 def napoleon_numpy_docstring_return_type_processor(  # noqa: PLR0913, PLR0917
@@ -138,13 +118,41 @@ def _patch_line_numbers() -> None:
     Body.doctest = _patched_body_doctest  # type: ignore[method-assign]
 
 
+@lru_cache
+def fix_directive_based_signature_formatting() -> None:
+    """
+    Patch Sphinx 9's new directive-based autodoc to disable overload detection.
+
+    The new architecture adds overload signatures without emitting autodoc-process-signature
+    for each one. By patching ModuleAnalyzer to clear overloads after analysis, we prevent
+    overload detection while preserving other functionality like attribute discovery.
+    """
+    try:
+        from sphinx.pycode import ModuleAnalyzer  # noqa: PLC0415
+    except ImportError:
+        return  # Not Sphinx 9+
+
+    # Store the original analyze method
+    original_analyze = ModuleAnalyzer.analyze
+
+    def patched_analyze(self: Any) -> None:
+        # Call the original analyze method
+        original_analyze(self)
+        # Then clear the overloads to prevent overload signature generation
+        self.overloads = {}
+
+    # Replace the analyze method
+    ModuleAnalyzer.analyze = patched_analyze  # type: ignore[method-assign]
+
+
 def install_patches(app: Sphinx) -> None:
     """
     Install the patches.
 
     :param app: the Sphinx app
     """
-    fix_autodoc_typehints_for_overloaded_methods()
+    # For Sphinx 9+ directive-based architecture
+    fix_directive_based_signature_formatting()
     patch_attribute_handling(app)
     _patch_google_docstring_lookup_annotation()
     fix_napoleon_numpy_docstring_return_type(app)

tests/roots/test-integration/conf.py

@@ -14,5 +14,3 @@
     "sphinx.ext.napoleon",
     "sphinx_autodoc_typehints",
 ]
-
-autodoc_use_legacy_class_based = True