Merge pull request #80 from jbms/feat-python-parameter-xrefs

Add Python synopsis and parameter cross-reference support

docs/api.rst

@@ -63,6 +63,7 @@ The following options can be customized for each object type using
 
       - ``std`` (including object types added using :py:obj:`sphinx.application.Sphinx.add_object_type`)
       - ``c`` and ``cpp``
+      - ``py``
 
    .. admonition:: Example
       :class: example
@@ -88,6 +89,7 @@ The following options can be customized for each object type using
 
       - ``std`` (including object types added using :py:obj:`sphinx.application.Sphinx.add_object_type`)
       - ``c`` and ``cpp``
+      - ``py``
 
    .. admonition:: Example
       :class: example

docs/cpp.rst

@@ -34,10 +34,9 @@ C++ domain customization
 
 .. confval:: cpp_qualify_parameter_ids
 
-   :python:`bool` specifying whether function, template, and macro parameters
-   should be assigned fully-qualified ids (for cross-linking purposes) of the
-   form ``<parent-id>-p-<param-name>`` based on the id of the parent
-   declaration.  Defaults to :python:`True`.
+   Specifies whether function, template, and macro parameters should be assigned
+   fully-qualified ids (for cross-linking purposes) of the form
+   ``<parent-id>-p-<param-name>`` based on the id of the parent declaration.
 
    If set to :python:`False`, instead the shorter unqualified id
    ``p-<param-name>`` is used.  This option should only be set to

docs/python.rst

@@ -75,3 +75,13 @@ Python domain customization
 
       The concise syntax is non-standard and not accepted by Python type
       checkers.
+
+.. confval:: python_qualify_parameter_ids
+
+   Specifies whether function parameters should be assigned fully-qualified ids
+   (for cross-linking purposes) of the form ``<parent-id>.<param-name>`` based
+   on the id of the parent declaration.
+
+   If set to :python:`False`, instead the shorter unqualified id
+   ``p-<param-name>`` is used.  This option should only be set to
+   :python:`False` if each Python declaration is on a separate page.

sphinx_immaterial/cpp_domain_fixes.py

@@ -394,16 +394,15 @@ def _resolve_xref_inner(
         ):
             refnode["classes"].append("desctype")
 
-        reftitle = refnode["reftitle"]
-
         if last_resolved_symbol is not None:
-            label = self.get_type_name(self.object_types[objtype])
-            reftitle += f" ({label})"
-
-            synopsis = getattr(last_resolved_symbol.declaration, SYNOPSIS_ATTR, None)
-            if synopsis:
-                reftitle += f" — {synopsis}"
-        refnode["reftitle"] = reftitle
+            refnode["reftitle"] = apidoc_formatting.format_object_description_tooltip(
+                env,
+                apidoc_formatting.get_object_description_options(
+                    env, self.name, objtype
+                ),
+                base_title=refnode["reftitle"],
+                synopsis=getattr(last_resolved_symbol.declaration, SYNOPSIS_ATTR, None),
+            )
 
         return refnode, objtype
 
@@ -721,7 +720,9 @@ def _add_parameter_documentation_ids(
 
     qualify_parameter_ids = env.config.cpp_qualify_parameter_ids
 
-    def cross_link_single_parameter(param_node: docutils.nodes.term) -> None:
+    def cross_link_single_parameter(
+        param_name: str, param_node: docutils.nodes.term
+    ) -> None:
         kind = param_node.get("param_kind")
 
         # Determine the number of unique declarations of this parameter.
@@ -886,7 +887,7 @@ def cross_link_single_parameter(param_node: docutils.nodes.term) -> None:
                     param_name = term.get("paramname")
                     if not param_name:
                         continue
-                    cross_link_single_parameter(term)
+                    cross_link_single_parameter(param_name, term)
 
 
 _FIRST_PARAMETER_ID_VERSIONS: Dict[str, int] = {"c": 1, "cpp": 4}
@@ -906,7 +907,6 @@ def _cross_link_parameters(
     content: docutils.nodes.Element,
     symbols,
 ) -> None:
-    """object-description-transform callback that cross-links parameters."""
     obj_desc = content.parent
 
     signodes = [

sphinx_immaterial/generic_synopses.py

@@ -23,20 +23,13 @@ def transform_content(self: object_class, contentnode) -> None:
         self.contentnode = contentnode
         orig_transform_content(self, contentnode)
 
-    orig_add_target_and_index = object_class.add_target_and_index
-
-    def add_target_and_index(
-        self: object_class, name: str, sig: str, signode: sphinx.addnodes.desc_signature
-    ) -> None:
-        self._saved_object_name = name
-        orig_add_target_and_index(self, name, sig, signode)
-
-    object_class.add_target_and_index = add_target_and_index
-
     object_class.transform_content = transform_content
 
     def after_content(self: object_class) -> None:
         orig_after_content(self)
+        noindex = "noindex" in self.options
+        if noindex:
+            return
         options = apidoc_formatting.get_object_description_options(
             self.env, self.domain, self.objtype
         )
@@ -47,7 +40,8 @@ def after_content(self: object_class) -> None:
             self.contentnode, generate_synopses
         )
         std = cast(StandardDomain, self.env.get_domain("std"))
-        std.data["synopses"][self.objtype, self._saved_object_name] = synopsis
+        for name in self.names:
+            std.data["synopses"][self.objtype, name] = synopsis
 
     object_class.after_content = after_content