Merge pull request #9695 from jakobandersen/js_nodes

JS, use more desc_sig_* nodes

Author: jakobandersen

CHANGES

@@ -15,6 +15,13 @@ Incompatible changes
 * #9672: the signature of
   :py:meth:`domains.py.PyObject.get_signature_prefix` has changed to
   return a list of nodes instead of a plain string.
+* #9695: ``domains.js.JSObject.display_prefix`` has been changed into a method
+  ``get_display_prefix`` which now returns a list of nodes
+  instead of a plain string.
+* #9695: The rendering of Javascript domain declarations is implemented
+  with more docutils nodes to allow better CSS styling.
+  It may break existing styling.
+
 
 Deprecated
 ----------
@@ -29,6 +36,7 @@ Features added
   for :rst:dir:`c:function` and :rst:dir:`c:macro`.
 * C++, added new info-field ``retval`` for :rst:dir:`cpp:function`.
 * #9672: More CSS classes on Python domain descriptions
+* #9695: More CSS classes on Javascript domain descriptions
 
 Bugs fixed
 ----------

doc/extdev/deprecated.rst

@@ -748,6 +748,11 @@ The following is a list of deprecated interfaces.
      - 4.0
      - ``sphinx.domains.std.StandardDomain.process_doc()``
 
+   * - ``sphinx.domains.js.JSObject.display_prefix``
+     - 
+     - 4.3
+     - ``sphinx.domains.js.JSObject.get_display_prefix()``
+
    * - ``sphinx.environment.NoUri``
      - 2.1
      - 3.0

sphinx/domains/javascript.py

@@ -41,9 +41,6 @@ class JSObject(ObjectDescription[Tuple[str, str]]):
     #: added
     has_arguments = False
 
-    #: what is displayed right before the documentation entry
-    display_prefix: str = None
-
     #: If ``allow_nesting`` is ``True``, the object prefixes will be accumulated
     #: based on directive nesting
     allow_nesting = False
@@ -53,6 +50,10 @@ class JSObject(ObjectDescription[Tuple[str, str]]):
         'noindexentry': directives.flag,
     }
 
+    def get_display_prefix(self) -> List[Node]:
+        #: what is displayed right before the documentation entry
+        return []
+
     def handle_signature(self, sig: str, signode: desc_signature) -> Tuple[str, str]:
         """Breaks down construct signatures
 
@@ -71,6 +72,7 @@ def handle_signature(self, sig: str, signode: desc_signature) -> Tuple[str, str]
         # If construct is nested, prefix the current prefix
         prefix = self.env.ref_context.get('js:object', None)
         mod_name = self.env.ref_context.get('js:module')
+
         name = member
         try:
             member_prefix, member_name = member.rsplit('.', 1)
@@ -91,14 +93,22 @@ def handle_signature(self, sig: str, signode: desc_signature) -> Tuple[str, str]
         signode['object'] = prefix
         signode['fullname'] = fullname
 
-        if self.display_prefix:
-            signode += addnodes.desc_annotation(self.display_prefix,
-                                                self.display_prefix)
+        display_prefix = self.get_display_prefix()
+        if display_prefix:
+            signode += addnodes.desc_annotation('', '', *display_prefix)
+
+        actual_prefix = None
         if prefix:
-            signode += addnodes.desc_addname(prefix + '.', prefix + '.')
+            actual_prefix = prefix
         elif mod_name:
-            signode += addnodes.desc_addname(mod_name + '.', mod_name + '.')
-        signode += addnodes.desc_name(name, name)
+            actual_prefix = mod_name
+        if actual_prefix:
+            addName = addnodes.desc_addname('', '')
+            for p in actual_prefix.split('.'):
+                addName += addnodes.desc_sig_name(p, p)
+                addName += addnodes.desc_sig_punctuation('.', '.')
+            signode += addName
+        signode += addnodes.desc_name('', '', addnodes.desc_sig_name(name, name))
         if self.has_arguments:
             if not arglist:
                 signode += addnodes.desc_parameterlist()
@@ -227,9 +237,13 @@ class JSCallable(JSObject):
 
 class JSConstructor(JSCallable):
     """Like a callable but with a different prefix."""
-    display_prefix = 'class '
+
     allow_nesting = True
 
+    def get_display_prefix(self) -> List[Node]:
+        return [addnodes.desc_sig_keyword('class', 'class'),
+                addnodes.desc_sig_space()]
+
 
 class JSModule(SphinxDirective):
     """

sphinx/domains/python.py

@@ -285,7 +285,8 @@ def _pseudo_parse_arglist(signode: desc_signature, arglist: str) -> None:
                 ends_open += 1
                 argument = argument[:-1].strip()
             if argument:
-                stack[-1] += addnodes.desc_parameter(argument, argument)
+                stack[-1] += addnodes.desc_parameter(
+                    '', '', addnodes.desc_sig_name(argument, argument))
             while ends_open:
                 stack.append(addnodes.desc_optional())
                 stack[-2] += stack[-1]

tests/test_domain_js.py

@@ -15,7 +15,8 @@
 
 from sphinx import addnodes
 from sphinx.addnodes import (desc, desc_annotation, desc_content, desc_name, desc_parameter,
-                             desc_parameterlist, desc_signature)
+                             desc_parameterlist, desc_sig_keyword, desc_sig_name,
+                             desc_sig_space, desc_signature)
 from sphinx.domains.javascript import JavaScriptDomain
 from sphinx.testing import restructuredtext
 from sphinx.testing.util import assert_node
@@ -184,11 +185,11 @@ def test_js_function(app):
     text = ".. js:function:: sum(a, b)"
     doctree = restructuredtext.parse(app, text)
     assert_node(doctree, (addnodes.index,
-                          [desc, ([desc_signature, ([desc_name, "sum"],
+                          [desc, ([desc_signature, ([desc_name, ([desc_sig_name, "sum"])],
                                                     desc_parameterlist)],
                                   [desc_content, ()])]))
-    assert_node(doctree[1][0][1], [desc_parameterlist, ([desc_parameter, "a"],
-                                                        [desc_parameter, "b"])])
+    assert_node(doctree[1][0][1], [desc_parameterlist, ([desc_parameter, ([desc_sig_name, "a"])],
+                                                        [desc_parameter, ([desc_sig_name, "b"])])])
     assert_node(doctree[0], addnodes.index,
                 entries=[("single", "sum() (built-in function)", "sum", "", None)])
     assert_node(doctree[1], addnodes.desc, domain="js", objtype="function", noindex=False)
@@ -198,8 +199,9 @@ def test_js_class(app):
     text = ".. js:class:: Application"
     doctree = restructuredtext.parse(app, text)
     assert_node(doctree, (addnodes.index,
-                          [desc, ([desc_signature, ([desc_annotation, "class "],
-                                                    [desc_name, "Application"],
+                          [desc, ([desc_signature, ([desc_annotation, ([desc_sig_keyword, 'class'],
+                                                                       desc_sig_space)],
+                                                    [desc_name, ([desc_sig_name, "Application"])],
                                                     [desc_parameterlist, ()])],
                                   [desc_content, ()])]))
     assert_node(doctree[0], addnodes.index,
@@ -211,7 +213,7 @@ def test_js_data(app):
     text = ".. js:data:: name"
     doctree = restructuredtext.parse(app, text)
     assert_node(doctree, (addnodes.index,
-                          [desc, ([desc_signature, desc_name, "name"],
+                          [desc, ([desc_signature, ([desc_name, ([desc_sig_name, "name"])])],
                                   [desc_content, ()])]))
     assert_node(doctree[0], addnodes.index,
                 entries=[("single", "name (global variable or constant)", "name", "", None)])

tests/test_domain_py.py

@@ -512,9 +512,9 @@ def test_optional_pyfunction_signature(app):
     assert_node(doctree[1], addnodes.desc, desctype="function",
                 domain="py", objtype="function", noindex=False)
     assert_node(doctree[1][0][1],
-                ([desc_parameter, "source"],
-                 [desc_optional, ([desc_parameter, "filename"],
-                                  [desc_optional, desc_parameter, "symbol"])]))
+                ([desc_parameter, ([desc_sig_name, "source"])],
+                 [desc_optional, ([desc_parameter, ([desc_sig_name, "filename"])],
+                                  [desc_optional, desc_parameter, ([desc_sig_name, "symbol"])])]))
 
 
 def test_pyexception_signature(app):