Improve SigElementFallbackTransform fallback logic. (#11311)

Co-authored-by: Adam Turner <[email protected]>

Author: picnixz

CHANGES

@@ -53,6 +53,10 @@ Features added
   Patch by Halldor Fannar.
 * #11570: Use short names when using :pep:`585` built-in generics.
   Patch by Riccardo Mori.
+* #11300: Improve ``SigElementFallbackTransform`` fallback logic and signature
+  text elements nodes. See :doc:`the documentation </extdev/nodes>` for more
+  details.
+  Patch by Bénédikt Tran.
 
 Bugs fixed
 ----------

doc/extdev/nodes.rst

@@ -35,6 +35,39 @@ and in :py:class:`desc_signature_line` nodes.
 .. autoclass:: desc_optional
 .. autoclass:: desc_annotation
 
+Nodes for signature text elements
+.................................
+
+These nodes inherit :py:class:`desc_sig_element` and are generally translated
+to ``docutils.nodes.inline`` by :py:class:`!SigElementFallbackTransform`.
+
+Extensions may create additional ``desc_sig_*``-like nodes but in order for
+:py:class:`!SigElementFallbackTransform` to translate them to inline nodes
+automatically, they must be added to :py:data:`SIG_ELEMENTS` via the class
+keyword argument `_sig_element=True` of :py:class:`desc_sig_element`, e.g.:
+
+   .. code-block:: python
+
+      class desc_custom_sig_node(desc_sig_element, _sig_element=True): ...
+
+For backwards compatibility, it is still possible to add the nodes directly
+using ``SIG_ELEMENTS.add(desc_custom_sig_node)``.
+
+.. autodata:: SIG_ELEMENTS
+   :no-value:
+
+.. autoclass:: desc_sig_element
+
+.. autoclass:: desc_sig_space
+.. autoclass:: desc_sig_name
+.. autoclass:: desc_sig_operator
+.. autoclass:: desc_sig_punctuation
+.. autoclass:: desc_sig_keyword
+.. autoclass:: desc_sig_keyword_type
+.. autoclass:: desc_sig_literal_number
+.. autoclass:: desc_sig_literal_string
+.. autoclass:: desc_sig_literal_char
+
 New admonition-like constructs
 ------------------------------
 

sphinx/addnodes.py

@@ -298,9 +298,20 @@ class desc_annotation(nodes.Part, nodes.Inline, nodes.FixedTextElement):
 # Leaf nodes for markup of text fragments
 #########################################
 
+#: A set of classes inheriting :class:`desc_sig_element`. Each node class
+#: is expected to be handled by the builder's translator class if the latter
+#: does not inherit from SphinxTranslator.
+#:
+#: This set can be extended manually by third-party extensions or
+#: by subclassing :class:`desc_sig_element` and using the class
+#: keyword argument `_sig_element=True`.
+SIG_ELEMENTS: set[type[desc_sig_element]] = set()
+
+
 # Signature text elements, generally translated to node.inline
 # in SigElementFallbackTransform.
-# When adding a new one, add it to SIG_ELEMENTS.
+# When adding a new one, add it to SIG_ELEMENTS via the class
+# keyword argument `_sig_element=True` (e.g., see `desc_sig_space`).
 
 class desc_sig_element(nodes.inline, _desc_classes_injector):
     """Common parent class of nodes for inline text of a signature."""
@@ -311,11 +322,17 @@ def __init__(self, rawsource: str = '', text: str = '',
         super().__init__(rawsource, text, *children, **attributes)
         self['classes'].extend(self.classes)
 
+    def __init_subclass__(cls, *, _sig_element=False, **kwargs):
+        super().__init_subclass__(**kwargs)
+        if _sig_element:
+            # add the class to the SIG_ELEMENTS set if asked
+            SIG_ELEMENTS.add(cls)
+
 
 # to not reinvent the wheel, the classes in the following desc_sig classes
 # are based on those used in Pygments
 
-class desc_sig_space(desc_sig_element):
+class desc_sig_space(desc_sig_element, _sig_element=True):
     """Node for a space in a signature."""
     classes = ["w"]
 
@@ -324,54 +341,46 @@ def __init__(self, rawsource: str = '', text: str = ' ',
         super().__init__(rawsource, text, *children, **attributes)
 
 
-class desc_sig_name(desc_sig_element):
+class desc_sig_name(desc_sig_element, _sig_element=True):
     """Node for an identifier in a signature."""
     classes = ["n"]
 
 
-class desc_sig_operator(desc_sig_element):
+class desc_sig_operator(desc_sig_element, _sig_element=True):
     """Node for an operator in a signature."""
     classes = ["o"]
 
 
-class desc_sig_punctuation(desc_sig_element):
+class desc_sig_punctuation(desc_sig_element, _sig_element=True):
     """Node for punctuation in a signature."""
     classes = ["p"]
 
 
-class desc_sig_keyword(desc_sig_element):
+class desc_sig_keyword(desc_sig_element, _sig_element=True):
     """Node for a general keyword in a signature."""
     classes = ["k"]
 
 
-class desc_sig_keyword_type(desc_sig_element):
+class desc_sig_keyword_type(desc_sig_element, _sig_element=True):
     """Node for a keyword which is a built-in type in a signature."""
     classes = ["kt"]
 
 
-class desc_sig_literal_number(desc_sig_element):
+class desc_sig_literal_number(desc_sig_element, _sig_element=True):
     """Node for a numeric literal in a signature."""
     classes = ["m"]
 
 
-class desc_sig_literal_string(desc_sig_element):
+class desc_sig_literal_string(desc_sig_element, _sig_element=True):
     """Node for a string literal in a signature."""
     classes = ["s"]
 
 
-class desc_sig_literal_char(desc_sig_element):
+class desc_sig_literal_char(desc_sig_element, _sig_element=True):
     """Node for a character literal in a signature."""
     classes = ["sc"]
 
 
-SIG_ELEMENTS = [desc_sig_space,
-                desc_sig_name,
-                desc_sig_operator,
-                desc_sig_punctuation,
-                desc_sig_keyword, desc_sig_keyword_type,
-                desc_sig_literal_number, desc_sig_literal_string, desc_sig_literal_char]
-
-
 ###############################################################
 # new admonition-like constructs
 

sphinx/transforms/post_transforms/__init__.py

@@ -250,18 +250,27 @@ def has_visitor(translator: type[nodes.NodeVisitor], node: type[Element]) -> boo
             # subclass of SphinxTranslator supports desc_sig_element nodes automatically.
             return
 
-        # for the leaf elements (desc_sig_element), the translator should support _all_
-        if not all(has_visitor(translator, node) for node in addnodes.SIG_ELEMENTS):
+        # for the leaf elements (desc_sig_element), the translator should support _all_,
+        # unless there exists a generic visit_desc_sig_element default visitor
+        if (not all(has_visitor(translator, node) for node in addnodes.SIG_ELEMENTS)
+                and not has_visitor(translator, addnodes.desc_sig_element)):
             self.fallback(addnodes.desc_sig_element)
 
         if not has_visitor(translator, addnodes.desc_inline):
             self.fallback(addnodes.desc_inline)
 
-    def fallback(self, nodeType: Any) -> None:
-        for node in self.document.findall(nodeType):
+    def fallback(self, node_type: Any) -> None:
+        """Translate nodes of type *node_type* to docutils inline nodes.
+
+        The original node type name is stored as a string in a private
+        ``_sig_node_type`` attribute if the latter did not exist.
+        """
+        for node in self.document.findall(node_type):
             newnode = nodes.inline()
             newnode.update_all_atts(node)
             newnode.extend(node)
+            # Only set _sig_node_type if not defined by the user
+            newnode.setdefault('_sig_node_type', node.tagname)
             node.replace_self(newnode)
 
 

tests/test_addnodes.py

@@ -0,0 +1,51 @@
+"""Test the non-trivial features in the :mod:`sphinx.addnodes` module."""
+
+from __future__ import annotations
+
+import pytest
+
+from sphinx import addnodes
+
+
+@pytest.fixture()
+def sig_elements() -> set[type[addnodes.desc_sig_element]]:
+    """Fixture returning the current ``addnodes.SIG_ELEMENTS`` set."""
+    original = addnodes.SIG_ELEMENTS.copy()  # safe copy of the current nodes
+    yield {*addnodes.SIG_ELEMENTS}  # temporary value to use during tests
+    addnodes.SIG_ELEMENTS = original  # restore the previous value
+
+
+def test_desc_sig_element_nodes(sig_elements):
+    """Test the registration of ``desc_sig_element`` subclasses."""
+
+    # expected desc_sig_* node classes (must be declared *after* reloading
+    # the module since otherwise the objects are not the correct ones)
+    EXPECTED_SIG_ELEMENTS = {
+        addnodes.desc_sig_space,
+        addnodes.desc_sig_name,
+        addnodes.desc_sig_operator,
+        addnodes.desc_sig_punctuation,
+        addnodes.desc_sig_keyword,
+        addnodes.desc_sig_keyword_type,
+        addnodes.desc_sig_literal_number,
+        addnodes.desc_sig_literal_string,
+        addnodes.desc_sig_literal_char,
+    }
+
+    assert addnodes.SIG_ELEMENTS == EXPECTED_SIG_ELEMENTS
+
+    # create a built-in custom desc_sig_element (added to SIG_ELEMENTS)
+    class BuiltInSigElementLikeNode(addnodes.desc_sig_element, _sig_element=True):
+        pass
+
+    # create a custom desc_sig_element (implicitly not added to SIG_ELEMENTS)
+    class Custom1SigElementLikeNode(addnodes.desc_sig_element):
+        pass
+
+    # create a custom desc_sig_element (explicitly not added to SIG_ELEMENTS)
+    class Custom2SigElementLikeNode(addnodes.desc_sig_element, _sig_element=False):
+        pass
+
+    assert BuiltInSigElementLikeNode in addnodes.SIG_ELEMENTS
+    assert Custom1SigElementLikeNode not in addnodes.SIG_ELEMENTS
+    assert Custom2SigElementLikeNode not in addnodes.SIG_ELEMENTS