feat(docs[_ext]): Link return type annotations to model and Python docs

why: "Returns: PaneInfo" rendered as plain code text with no hyperlink.
All model classes are in objects.inv and should be clickable.
what:
- Add _make_type_xref() that creates pending_xref nodes for type names
- Known model classes (PaneInfo, etc.) resolve to reference/api/models/
- Builtins (str, list) resolve to Python docs via intersphinx
- Handle list[X] generics with separate xrefs for container and inner
- Replace _make_literal() with _make_type_xref() for return annotations
- Add 4 tests: model class, list[model], builtin, unknown type

Author: tony

docs/_ext/fastmcp_autodoc.py

@@ -30,6 +30,7 @@
 from dataclasses import dataclass
 
 from docutils import nodes
+from sphinx import addnodes
 from sphinx.application import Sphinx
 from sphinx.util.docutils import SphinxDirective
 
@@ -60,6 +61,20 @@
 TAG_MUTATING = "mutating"
 TAG_DESTRUCTIVE = "destructive"
 
+_MODEL_MODULE = "libtmux_mcp.models"
+_MODEL_CLASSES: set[str] = {
+    "SessionInfo",
+    "WindowInfo",
+    "PaneInfo",
+    "PaneContentMatch",
+    "ServerInfo",
+    "OptionResult",
+    "OptionSetResult",
+    "EnvironmentResult",
+    "EnvironmentSetResult",
+    "WaitForTextResult",
+}
+
 
 # ---------------------------------------------------------------------------
 # Data classes
@@ -278,6 +293,42 @@ def _make_literal(text: str) -> nodes.literal:
     return nodes.literal("", text)
 
 
+def _single_type_xref(name: str) -> addnodes.pending_xref:
+    """Create a ``pending_xref`` for a single type name.
+
+    Known model classes are qualified to ``libtmux_mcp.models.X``.
+    Builtins (``str``, ``list``, ``int``, etc.) target the Python domain.
+    """
+    target = f"{_MODEL_MODULE}.{name}" if name in _MODEL_CLASSES else name
+    return addnodes.pending_xref(
+        "",
+        nodes.literal("", name),
+        refdomain="py",
+        reftype="class",
+        reftarget=target,
+    )
+
+
+def _make_type_xref(type_str: str) -> nodes.paragraph:
+    """Render a return type annotation with cross-reference links.
+
+    Handles ``list[X]`` generics and bare type names.
+    Each type component becomes a ``pending_xref`` that Sphinx resolves
+    into a hyperlink (internal or intersphinx).
+    """
+    para = nodes.paragraph("")
+    m = re.match(r"^(list|set|tuple)\[(.+)\]$", type_str)
+    if m:
+        container, inner = m.group(1), m.group(2)
+        para += _single_type_xref(container)
+        para += nodes.Text("[")
+        para += _single_type_xref(inner)
+        para += nodes.Text("]")
+    else:
+        para += _single_type_xref(type_str)
+    return para
+
+
 def _make_para(*children: nodes.Node | str) -> nodes.paragraph:
     """Create a paragraph from mixed text and node children."""
     para = nodes.paragraph("")
@@ -533,10 +584,12 @@ def _build_tool_section(self, tool: ToolInfo) -> list[nodes.Node]:
 
         # Returns (promoted — high-signal for tool selection)
         if tool.return_annotation:
-            section += _make_para(
-                nodes.strong("", "Returns: "),
-                _make_literal(tool.return_annotation),
-            )
+            returns_para = nodes.paragraph("")
+            returns_para += nodes.strong("", "Returns: ")
+            type_para = _make_type_xref(tool.return_annotation)
+            for child in type_para.children:
+                returns_para += child.deepcopy()
+            section += returns_para
 
         return [section]
 

tests/docs/_ext/test_fastmcp_autodoc.py

@@ -443,6 +443,62 @@ def test_safety_badge_classes() -> None:
     assert "sd-bg-danger" in badge["classes"]
 
 
+# ---------------------------------------------------------------------------
+# _make_type_xref
+# ---------------------------------------------------------------------------
+
+
+def test_make_type_xref_model_class() -> None:
+    """_make_type_xref creates pending_xref for known model classes."""
+    from sphinx import addnodes
+
+    para = fastmcp_autodoc._make_type_xref("PaneInfo")
+    assert len(para.children) == 1
+    xref = para.children[0]
+    assert isinstance(xref, addnodes.pending_xref)
+    assert xref["refdomain"] == "py"
+    assert xref["reftype"] == "class"
+    assert xref["reftarget"] == "libtmux_mcp.models.PaneInfo"
+    assert xref.children[0].astext() == "PaneInfo"
+
+
+def test_make_type_xref_list_of_model() -> None:
+    """_make_type_xref handles list[SessionInfo] with xrefs for both."""
+    from sphinx import addnodes
+
+    para = fastmcp_autodoc._make_type_xref("list[SessionInfo]")
+    # list xref, "[", SessionInfo xref, "]"
+    assert len(para.children) == 4
+    list_xref = para.children[0]
+    assert isinstance(list_xref, addnodes.pending_xref)
+    assert list_xref["reftarget"] == "list"
+
+    inner_xref = para.children[2]
+    assert isinstance(inner_xref, addnodes.pending_xref)
+    assert inner_xref["reftarget"] == "libtmux_mcp.models.SessionInfo"
+
+
+def test_make_type_xref_builtin() -> None:
+    """_make_type_xref creates pending_xref for builtins like str."""
+    from sphinx import addnodes
+
+    para = fastmcp_autodoc._make_type_xref("str")
+    xref = para.children[0]
+    assert isinstance(xref, addnodes.pending_xref)
+    assert xref["reftarget"] == "str"
+    assert xref["refdomain"] == "py"
+
+
+def test_make_type_xref_unknown() -> None:
+    """_make_type_xref still creates pending_xref for unknown types."""
+    from sphinx import addnodes
+
+    para = fastmcp_autodoc._make_type_xref("SomeUnknown")
+    xref = para.children[0]
+    assert isinstance(xref, addnodes.pending_xref)
+    assert xref["reftarget"] == "SomeUnknown"
+
+
 # ---------------------------------------------------------------------------
 # SECTION_BADGE_MAP + _add_section_badges
 # ---------------------------------------------------------------------------