Decl styling, more nodes and C++ conversion

sphinx/addnodes.py

@@ -154,6 +154,10 @@ class desc_signature_line(nodes.Part, nodes.Inline, nodes.FixedTextElement):
 
 # nodes to use within a desc_signature or desc_signature_line
 
+class desc_name(nodes.Part, nodes.Inline, nodes.FixedTextElement):
+    """Node for the main object name."""
+
+
 class desc_addname(nodes.Part, nodes.Inline, nodes.FixedTextElement):
     """Node for additional name parts (module name, class name)."""
 
@@ -168,14 +172,11 @@ class desc_type(nodes.Part, nodes.Inline, nodes.FixedTextElement):
 
 class desc_returns(desc_type):
     """Node for a "returns" annotation (a la -> in Python)."""
+
     def astext(self) -> str:
         return ' -> ' + super().astext()
 
 
-class desc_name(nodes.Part, nodes.Inline, nodes.FixedTextElement):
-    """Node for the main object name."""
-
-
 class desc_parameterlist(nodes.Part, nodes.Inline, nodes.FixedTextElement):
     """Node for a general parameter list."""
     child_text_separator = ', '
@@ -207,6 +208,10 @@ class desc_content(nodes.General, nodes.Element):
     """
 
 
+# Signature text elements, generally translated to node.inline
+# in SigElementFallbackTransform.
+# When adding a new one, add it to SIG_ELEMENTS.
+
 class desc_sig_element(nodes.inline):
     """Common parent class of nodes for inline text of a signature."""
     classes: List[str] = []
@@ -217,8 +222,19 @@ class desc_sig_element(nodes.inline):
         self['classes'].extend(self.classes)
 
 
+# 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):
+    """Node for a space in a signature."""
+    classes = ["w"]
+
+    def __init__(self) -> None:
+        super().__init__(' ', ' ')
+
+
 class desc_sig_name(desc_sig_element):
-    """Node for a name in a signature."""
+    """Node for an identifier in a signature."""
     classes = ["n"]
 
 
@@ -228,10 +244,43 @@ class desc_sig_operator(desc_sig_element):
 
 
 class desc_sig_punctuation(desc_sig_element):
-    """Node for a punctuation in a signature."""
+    """Node for punctuation in a signature."""
     classes = ["p"]
 
 
+class desc_sig_keyword(desc_sig_element):
+    """Node for a general keyword in a signature."""
+    classes = ["k"]
+
+
+class desc_sig_keyword_type(desc_sig_element):
+    """Node for a keyword which is a built-in type in a signature."""
+    classes = ["kt"]
+
+
+class desc_sig_literal_number(desc_sig_element):
+    """Node for a numeric literal in a signature."""
+    classes = ["m"]
+
+
+class desc_sig_literal_string(desc_sig_element):
+    """Node for a string literal in a signature."""
+    classes = ["s"]
+
+
+class desc_sig_literal_char(desc_sig_element):
+    """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
 
 class versionmodified(nodes.Admonition, nodes.TextElement):
@@ -336,6 +385,7 @@ class pending_xref(nodes.Inline, nodes.Element):
     These nodes are resolved before writing output, in
     BuildEnvironment.resolve_references.
     """
+    child_text_separator = ''
 
 
 class pending_xref_condition(nodes.Inline, nodes.TextElement):
@@ -424,9 +474,8 @@ def setup(app: "Sphinx") -> Dict[str, Any]:
     app.add_node(desc_optional)
     app.add_node(desc_annotation)
     app.add_node(desc_content)
-    app.add_node(desc_sig_name)
-    app.add_node(desc_sig_operator)
-    app.add_node(desc_sig_punctuation)
+    for n in SIG_ELEMENTS:
+        app.add_node(n)
     app.add_node(versionmodified)
     app.add_node(seealso)
     app.add_node(productionlist)

sphinx/themes/basic/static/basic.css_t

@@ -508,6 +508,30 @@ table.hlist td {
     vertical-align: top;
 }
 
+/* -- object description styles --------------------------------------------- */
+
+.sig-name, code.descname {
+    background-color: transparent;
+    font-weight: bold;
+    font-size: 1.2em;
+}
+
+.sig-prename, code.descclassname {
+    background-color: transparent;
+}
+
+.optional {
+    font-size: 1.3em;
+}
+
+.sig-paren {
+    font-size: larger;
+}
+
+.sig-param.n {
+	font-style: italic;
+}
+
 
 /* -- other body styles ----------------------------------------------------- */
 
@@ -634,14 +658,6 @@ dl.glossary dt {
     font-size: 1.1em;
 }
 
-.optional {
-    font-size: 1.3em;
-}
-
-.sig-paren {
-    font-size: larger;
-}
-
 .versionmodified {
     font-style: italic;
 }
@@ -786,16 +802,6 @@ div.literal-block-wrapper {
     margin: 1em 0;
 }
 
-code.descname {
-    background-color: transparent;
-    font-weight: bold;
-    font-size: 1.2em;
-}
-
-code.descclassname {
-    background-color: transparent;
-}
-
 code.xref, a code {
     background-color: transparent;
     font-weight: bold;

sphinx/transforms/post_transforms/__init__.py

@@ -209,10 +209,6 @@ class SigElementFallbackTransform(SphinxPostTransform):
     """Fallback desc_sig_element nodes to inline if translator does not supported them."""
     default_priority = 200
 
-    SIG_ELEMENTS = [addnodes.desc_sig_name,
-                    addnodes.desc_sig_operator,
-                    addnodes.desc_sig_punctuation]
-
     def run(self, **kwargs: Any) -> None:
         def has_visitor(translator: Type[nodes.NodeVisitor], node: Type[Element]) -> bool:
             return hasattr(translator, "visit_%s" % node.__name__)
@@ -222,7 +218,7 @@ class SigElementFallbackTransform(SphinxPostTransform):
             # subclass of SphinxTranslator supports desc_sig_element nodes automatically.
             return
 
-        if all(has_visitor(translator, node) for node in self.SIG_ELEMENTS):
+        if all(has_visitor(translator, node) for node in addnodes.SIG_ELEMENTS):
             # the translator supports all desc_sig_element nodes
             return
         else:

tests/test_domain_cpp.py

@@ -73,6 +73,7 @@ def _check(name, input, idDict, output, key, asTextOutput):
         print("Input:    ", input)
         print("astext(): ", resAsText)
         print("Expected: ", outputAsText)
+        print("Node:", parentNode)
         raise DefinitionError("")
 
     idExpected = [None]
@@ -743,6 +744,9 @@ def test_anon_definitions():
     check('class', '@1', {3: "Ut1_1"}, asTextOutput='class [anonymous]')
     check('class', '@a::A', {3: "NUt1_a1AE"}, asTextOutput='class [anonymous]::A')
 
+    check('function', 'int f(int @a)', {1: 'f__i', 2: '1fi'},
+          asTextOutput='int f(int [anonymous])')
+
 
 def test_templates():
     check('class', "A<T>", {2: "IE1AI1TE"}, output="template<> {key}A<T>")

tests/test_ext_intersphinx.py

@@ -258,10 +258,10 @@ def test_missing_reference_cppdomain(tempdir, app, status, warning):
             '<span class="pre">Bar</span></code></a>' in html)
     assert ('<a class="reference external"'
             ' href="https://docs.python.org/index.html#foons"'
-            ' title="(in foo v2.0)"><span class="pre">foons</span></a>' in html)
+            ' title="(in foo v2.0)"><span class="n">foons</span></a>' in html)
     assert ('<a class="reference external"'
             ' href="https://docs.python.org/index.html#foons_bartype"'
-            ' title="(in foo v2.0)"><span class="pre">bartype</span></a>' in html)
+            ' title="(in foo v2.0)"><span class="n">bartype</span></a>' in html)
 
 
 def test_missing_reference_jsdomain(tempdir, app, status, warning):