diff --git a/CHANGES b/CHANGES index 4343ffb3ed3..ddaee44ac98 100644 --- a/CHANGES +++ b/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 ---------- diff --git a/doc/extdev/deprecated.rst b/doc/extdev/deprecated.rst index bca49370b35..72220811f04 100644 --- a/doc/extdev/deprecated.rst +++ b/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 diff --git a/sphinx/domains/javascript.py b/sphinx/domains/javascript.py index 565d681dcf2..e2dfb72b12c 100644 --- a/sphinx/domains/javascript.py +++ b/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): """ diff --git a/sphinx/domains/python.py b/sphinx/domains/python.py index b68583cce06..cd02eaad563 100644 --- a/sphinx/domains/python.py +++ b/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] diff --git a/tests/test_domain_js.py b/tests/test_domain_js.py index 1fb865d4b8c..434513063d5 100644 --- a/tests/test_domain_js.py +++ b/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)]) diff --git a/tests/test_domain_py.py b/tests/test_domain_py.py index 140cb97109e..682ea76e199 100644 --- a/tests/test_domain_py.py +++ b/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):