🐛 fix(parser): stop shadowing intersphinx roles in the type role (#761)

Author: gaborbernat

src/sphinx_autodoc_typehints/_formats/_sphinx.py

@@ -15,6 +15,7 @@
 from docutils.parsers.rst import Directive, directives
 from docutils.utils import new_document
 from sphinx.parsers import RSTParser
+from sphinx.util import logging
 
 from sphinx_autodoc_typehints._parser import _RstSnippetParser
 
@@ -112,7 +113,10 @@ def _safe_directive_lookup(
     # dispatcher layered on top of it, losing the external+ roles (#753)
     directives.directive = _safe_directive_lookup  # type: ignore[assignment]
     try:
-        _RstSnippetParser().parse(inputstr, doc)
+        # Whatever this parse has to say about the docstring, the real parse says again with the
+        # right line number, so its warnings are only duplicates
+        with logging.suppress_logging():
+            _RstSnippetParser().parse(inputstr, doc)
     finally:
         directives.directive = original_lookup
     return doc

src/sphinx_autodoc_typehints/_parser.py

@@ -6,7 +6,6 @@
 
 from docutils.utils import new_document
 from sphinx.parsers import RSTParser
-from sphinx.util.docutils import sphinx_domains
 
 if TYPE_CHECKING:
     import optparse
@@ -23,9 +22,9 @@ def decorate(_content: StringList) -> None:  # ty: ignore[invalid-method-overrid
 
 
 def parse(inputstr: str, settings: Values | optparse.Values) -> nodes.document:
-    """Parse inputstr and return a docutils document."""
+    """Parse inputstr and return a docutils document. Callers must already be inside ``sphinx_domains``."""
     doc = new_document("", settings=settings)  # ty: ignore[invalid-argument-type]
-    with sphinx_domains(settings.env):
-        parser = _RstSnippetParser()
-        parser.parse(inputstr, doc)
+    # Entering sphinx_domains again shadows the intersphinx dispatcher layered on top of it,
+    # losing the external+ roles the read phase resolves (#753)
+    _RstSnippetParser().parse(inputstr, doc)
     return doc

tests/roots/test-intersphinx-external-role/conf.py

@@ -3,9 +3,13 @@
 import pathlib
 import sys
 import zlib
+from typing import TYPE_CHECKING, Any
 
 sys.path.insert(0, str(pathlib.Path(__file__).parent))
 
+if TYPE_CHECKING:
+    from sphinx.config import Config
+
 master_doc = "index"
 
 extensions = [
@@ -23,3 +27,8 @@
     b"# The remainder of this file is compressed using zlib.\n" + zlib.compress(b"index std:doc -1 index.html Demo\n")
 )
 intersphinx_mapping = {"demo": ("https://example.org/demo/", str(_INVENTORY))}
+
+
+def typehints_formatter(annotation: Any, config: Config) -> str | None:  # ruff:ignore[unused-function-argument]
+    """Render one annotation as an intersphinx role, which the type role parses on its own."""
+    return ":external+demo:doc:`the demo docs <index>`" if annotation is bool else None

tests/roots/test-intersphinx-external-role/demo_module.py

@@ -1,10 +1,11 @@
 from __future__ import annotations
 
 
-def probe(x: int) -> int:
+def probe(x: int, flag: bool) -> int:
     """
     Summarize.
 
     :param x: see :external+demo:doc:`the demo docs <index>`.
+    :param flag: a flag whose type renders as a role.
     """
-    return x
+    return x if flag else -x

tests/roots/test-intersphinx-missing-inventory/conf.py

@@ -0,0 +1,15 @@
+from __future__ import annotations
+
+import pathlib
+import sys
+
+sys.path.insert(0, str(pathlib.Path(__file__).parent))
+
+master_doc = "index"
+
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.intersphinx",
+    "sphinx_autodoc_typehints",
+]
+intersphinx_mapping: dict[str, tuple[str, str]] = {}

tests/roots/test-intersphinx-missing-inventory/demo_missing.py

@@ -0,0 +1,10 @@
+from __future__ import annotations
+
+
+def probe(x: int) -> int:
+    """
+    Summarize.
+
+    :param x: see :external+nope:doc:`the missing docs <index>`.
+    """
+    return x

tests/roots/test-intersphinx-missing-inventory/index.rst

@@ -0,0 +1,4 @@
+Demo
+====
+
+.. autofunction:: demo_missing.probe

tests/test_safe_parse.py

@@ -74,7 +74,15 @@ def run(self) -> list:
 def test_intersphinx_role_resolves_during_snippet_parse(
     app: SphinxTestApp, status: StringIO, warning: StringIO
 ) -> None:
-    """The snippet parse must not shadow the intersphinx role dispatcher (#753)."""
+    """Neither the snippet parse nor the type role may shadow the intersphinx dispatcher (#753)."""
     app.build()
     assert "build succeeded" in status.getvalue()
-    assert "unknown role name" not in warning.getvalue()
+    assert not warning.getvalue()
+
+
+@pytest.mark.sphinx("text", testroot="intersphinx-missing-inventory")
+def test_snippet_parse_stays_quiet(app: SphinxTestApp, status: StringIO, warning: StringIO) -> None:
+    """A reference the role cannot resolve is reported by the real parse alone (#753)."""
+    app.build()
+    assert "build succeeded" in status.getvalue()
+    assert warning.getvalue().count("inventory for external cross-reference not found") == 1