🧪 test(docstring): pin what a nested handler restores

tests/roots/test-reentrant-formatter/conf.py

@@ -0,0 +1,32 @@
+from __future__ import annotations
+
+import pathlib
+import sys
+from typing import TYPE_CHECKING, Any
+
+from sphinx_autodoc_typehints import process_docstring
+
+sys.path.insert(0, str(pathlib.Path(__file__).parent))
+
+master_doc = "index"
+
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx_autodoc_typehints",
+]
+
+if TYPE_CHECKING:
+    from sphinx.application import Sphinx
+    from sphinx.config import Config
+
+
+def setup(app: Sphinx) -> None:
+    """Install a formatter that documents a second object, re-entering the docstring handler."""
+
+    def inner(flag: str) -> str: ...
+
+    def formatter(annotation: Any, config: Config) -> None:  # ruff:ignore[unused-function-argument]
+        if annotation is bool:
+            process_docstring(app, "function", "inner_mod.inner", inner, None, ["Inner.", "", ":return: it"])
+
+    app.config.typehints_formatter = formatter

tests/roots/test-reentrant-formatter/demo_reentrant.py

@@ -0,0 +1,11 @@
+from __future__ import annotations
+
+
+def outer(flag: bool) -> bool:
+    """
+    Outer.
+
+    :param flag: the flag
+    :return: it
+    """
+    return flag

tests/roots/test-reentrant-formatter/index.rst

@@ -0,0 +1 @@
+.. autofunction:: demo_reentrant.outer

tests/test_init.py

@@ -433,21 +433,23 @@ def test_setup_returns_version() -> None:
 
 
 def test_process_docstring_reentrant_call_keeps_outer_state() -> None:
-    """A formatter documenting a second object must not break the outer teardown (#750)."""
+    """A nested call must hand the outer one its own state back (#750)."""
 
     def inner(flag: str) -> str: ...
 
     def outer(flag: bool) -> bool: ...
 
     app = make_docstring_app()
+    prefix_after_nesting = []
 
-    def formatter(annotation: Any, config: Config) -> None:  # ruff:ignore[unused-function-argument]
+    def formatter(annotation: Any, config: Config) -> None:
         if annotation is bool:
-            process_docstring(app, "function", "test.inner", inner, None, ["Inner.", "", ":return: it"])
+            process_docstring(app, "function", "inner_mod.inner", inner, None, ["Inner.", "", ":return: it"])
+            prefix_after_nesting.append(config._typehints_module_prefix)  # ruff:ignore[private-member-access]
 
     app.config.typehints_formatter = formatter
     lines = ["Outer.", "", ":param flag: the flag", ":return: it"]
-    process_docstring(app, "function", "test.outer", outer, None, lines)
+    process_docstring(app, "function", "outer_mod.outer", outer, None, lines)
     bool_type = ":sphinx_autodoc_typehints_type:`\\:py\\:class\\:\\`bool\\``"
     assert lines == [
         "Outer.",
@@ -458,3 +460,4 @@ def formatter(annotation: Any, config: Config) -> None:  # ruff:ignore[unused-fu
         f":rtype: {bool_type}",
         ":return: it",
     ]
+    assert prefix_after_nesting == ["outer_mod", "outer_mod"]

tests/test_sphinx_autodoc_typehints.py

@@ -395,6 +395,14 @@ def test_resolve_typing_guard_attrs_imports(app: SphinxTestApp, status: StringIO
     assert not warning.getvalue()
 
 
+@pytest.mark.sphinx("text", testroot="reentrant-formatter")
+def test_reentrant_formatter_keeps_the_build_alive(app: SphinxTestApp, status: StringIO, warning: StringIO) -> None:
+    """A formatter documenting a second object must not abort the build (#750)."""
+    app.build()
+    assert "build succeeded" in status.getvalue()
+    assert not warning.getvalue()
+
+
 @pytest.mark.sphinx("text", testroot="dummy")
 def test_sphinx_output_formatter_no_use_rtype(app: SphinxTestApp, status: StringIO) -> None:
     app.config.master_doc = "simple_no_use_rtype"  # create flag