From 37083fcc1ab12fbc6d53213a92a132191eb79fc1 Mon Sep 17 00:00:00 2001 From: Jakob Lykke Andersen Date: Sat, 2 Oct 2021 13:30:11 +0200 Subject: [PATCH 1/8] js nodes, update display_prefix --- CHANGES | 3 +++ sphinx/domains/javascript.py | 19 ++++++++++++------- tests/test_domain_js.py | 6 ++++-- 3 files changed, 19 insertions(+), 9 deletions(-) diff --git a/CHANGES b/CHANGES index 4343ffb3ed3..b7feb8fa156 100644 --- a/CHANGES +++ b/CHANGES @@ -15,6 +15,9 @@ 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. +* ``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. Deprecated ---------- diff --git a/sphinx/domains/javascript.py b/sphinx/domains/javascript.py index 565d681dcf2..7abfad48295 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[nodes.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 @@ -91,9 +92,9 @@ 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) if prefix: signode += addnodes.desc_addname(prefix + '.', prefix + '.') elif mod_name: @@ -227,9 +228,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[nodes.Node]: + return [addnodes.desc_sig_keyword('class', 'class'), + addnodes.desc_sig_space()] + class JSModule(SphinxDirective): """ diff --git a/tests/test_domain_js.py b/tests/test_domain_js.py index 1fb865d4b8c..535321d9fed 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_space, + desc_signature) from sphinx.domains.javascript import JavaScriptDomain from sphinx.testing import restructuredtext from sphinx.testing.util import assert_node @@ -198,7 +199,8 @@ 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, ([desc_signature, ([desc_annotation, ([desc_sig_keyword, 'class'], + desc_sig_space)], [desc_name, "Application"], [desc_parameterlist, ()])], [desc_content, ()])])) From 1c124e025866c61e20c7f0dceb13e772ff645e74 Mon Sep 17 00:00:00 2001 From: Jakob Lykke Andersen Date: Sat, 2 Oct 2021 13:43:25 +0200 Subject: [PATCH 2/8] js nodes, update prefix rendering --- sphinx/domains/javascript.py | 13 +++++++++++-- 1 file changed, 11 insertions(+), 2 deletions(-) diff --git a/sphinx/domains/javascript.py b/sphinx/domains/javascript.py index 7abfad48295..450c9c7618a 100644 --- a/sphinx/domains/javascript.py +++ b/sphinx/domains/javascript.py @@ -72,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) @@ -95,10 +96,18 @@ def handle_signature(self, sig: str, signode: desc_signature) -> Tuple[str, str] display_prefix = self.get_display_prefix() if display_prefix: signode += addnodes.desc_annotation('', '', *display_prefix) + + actualPrefix = None if prefix: - signode += addnodes.desc_addname(prefix + '.', prefix + '.') + actualPrefix = prefix elif mod_name: - signode += addnodes.desc_addname(mod_name + '.', mod_name + '.') + actualPrefix = mod_name + if actualPrefix: + addName = addnodes.desc_addname('', '') + for p in actualPrefix.split('.'): + addName += addnodes.desc_sig_name(p, p) + addName += addnodes.desc_sig_punctuation('.', '.') + signode += addName signode += addnodes.desc_name(name, name) if self.has_arguments: if not arglist: From 06d3d7356edc0023a6e4fd2deab0320601ef96b9 Mon Sep 17 00:00:00 2001 From: Jakob Lykke Andersen Date: Sat, 2 Oct 2021 13:48:29 +0200 Subject: [PATCH 3/8] js nodes, update name rendering --- sphinx/domains/javascript.py | 2 +- tests/test_domain_js.py | 10 +++++----- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/sphinx/domains/javascript.py b/sphinx/domains/javascript.py index 450c9c7618a..7d5958590c3 100644 --- a/sphinx/domains/javascript.py +++ b/sphinx/domains/javascript.py @@ -108,7 +108,7 @@ def handle_signature(self, sig: str, signode: desc_signature) -> Tuple[str, str] addName += addnodes.desc_sig_name(p, p) addName += addnodes.desc_sig_punctuation('.', '.') signode += addName - signode += addnodes.desc_name(name, name) + signode += addnodes.desc_name('', '', addnodes.desc_sig_name(name, name)) if self.has_arguments: if not arglist: signode += addnodes.desc_parameterlist() diff --git a/tests/test_domain_js.py b/tests/test_domain_js.py index 535321d9fed..4680d88cc7e 100644 --- a/tests/test_domain_js.py +++ b/tests/test_domain_js.py @@ -15,8 +15,8 @@ from sphinx import addnodes from sphinx.addnodes import (desc, desc_annotation, desc_content, desc_name, desc_parameter, - desc_parameterlist, desc_sig_keyword, desc_sig_space, - 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 @@ -185,7 +185,7 @@ 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"], @@ -201,7 +201,7 @@ def test_js_class(app): assert_node(doctree, (addnodes.index, [desc, ([desc_signature, ([desc_annotation, ([desc_sig_keyword, 'class'], desc_sig_space)], - [desc_name, "Application"], + [desc_name, ([desc_sig_name, "Application"])], [desc_parameterlist, ()])], [desc_content, ()])])) assert_node(doctree[0], addnodes.index, @@ -213,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)]) From a64196f048ab99e3e482418e73f3ae08145f11bc Mon Sep 17 00:00:00 2001 From: Jakob Lykke Andersen Date: Sat, 2 Oct 2021 13:56:30 +0200 Subject: [PATCH 4/8] js/py nodes, update arglist rendering --- sphinx/domains/python.py | 3 ++- tests/test_domain_js.py | 4 ++-- tests/test_domain_py.py | 6 +++--- 3 files changed, 7 insertions(+), 6 deletions(-) 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 4680d88cc7e..434513063d5 100644 --- a/tests/test_domain_js.py +++ b/tests/test_domain_js.py @@ -188,8 +188,8 @@ def test_js_function(app): [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) 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): From 422068618632524914643bfb7dd4d5658f60f7b9 Mon Sep 17 00:00:00 2001 From: Jakob Lykke Andersen Date: Sat, 2 Oct 2021 13:58:05 +0200 Subject: [PATCH 5/8] js (and py) nodes, update CHANGES --- CHANGES | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/CHANGES b/CHANGES index b7feb8fa156..2cd3372d021 100644 --- a/CHANGES +++ b/CHANGES @@ -18,6 +18,10 @@ Incompatible changes * ``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. +* The rendering of Javascript domain declarations is implemented + with more docutils nodes to allow better CSS styling. + It may break existing styling. + Deprecated ---------- @@ -32,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 +* More CSS classes on Javascript domain descriptions Bugs fixed ---------- From 44835bff3387fbf4aec709f77c7cbf7ba947c307 Mon Sep 17 00:00:00 2001 From: Jakob Lykke Andersen Date: Sun, 3 Oct 2021 09:49:34 +0200 Subject: [PATCH 6/8] js nodes, update CHANGES and rename variable --- CHANGES | 6 +++--- sphinx/domains/javascript.py | 10 +++++----- 2 files changed, 8 insertions(+), 8 deletions(-) diff --git a/CHANGES b/CHANGES index 2cd3372d021..ddaee44ac98 100644 --- a/CHANGES +++ b/CHANGES @@ -15,10 +15,10 @@ 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. -* ``domains.js.JSObject.display_prefix`` has been changed into a method +* #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. -* The rendering of Javascript domain declarations is implemented +* #9695: The rendering of Javascript domain declarations is implemented with more docutils nodes to allow better CSS styling. It may break existing styling. @@ -36,7 +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 -* More CSS classes on Javascript domain descriptions +* #9695: More CSS classes on Javascript domain descriptions Bugs fixed ---------- diff --git a/sphinx/domains/javascript.py b/sphinx/domains/javascript.py index 7d5958590c3..e48f821e8e4 100644 --- a/sphinx/domains/javascript.py +++ b/sphinx/domains/javascript.py @@ -97,14 +97,14 @@ def handle_signature(self, sig: str, signode: desc_signature) -> Tuple[str, str] if display_prefix: signode += addnodes.desc_annotation('', '', *display_prefix) - actualPrefix = None + actual_prefix = None if prefix: - actualPrefix = prefix + actual_prefix = prefix elif mod_name: - actualPrefix = mod_name - if actualPrefix: + actual_prefix = mod_name + if actual_prefix: addName = addnodes.desc_addname('', '') - for p in actualPrefix.split('.'): + for p in actual_prefix.split('.'): addName += addnodes.desc_sig_name(p, p) addName += addnodes.desc_sig_punctuation('.', '.') signode += addName From 1fe87938e2cde5b09b90d9289004b3a320f95b25 Mon Sep 17 00:00:00 2001 From: Jakob Lykke Andersen Date: Sun, 3 Oct 2021 09:56:10 +0200 Subject: [PATCH 7/8] js nodes, docs, add entry in deprecation/removal table --- doc/extdev/deprecated.rst | 5 +++++ 1 file changed, 5 insertions(+) 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 From 6321d144474243195c37611528d358b88199ff1a Mon Sep 17 00:00:00 2001 From: Jakob Lykke Andersen Date: Sun, 3 Oct 2021 09:57:14 +0200 Subject: [PATCH 8/8] js nodes, nodes.Node -> Node --- sphinx/domains/javascript.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/sphinx/domains/javascript.py b/sphinx/domains/javascript.py index e48f821e8e4..e2dfb72b12c 100644 --- a/sphinx/domains/javascript.py +++ b/sphinx/domains/javascript.py @@ -50,7 +50,7 @@ class JSObject(ObjectDescription[Tuple[str, str]]): 'noindexentry': directives.flag, } - def get_display_prefix(self) -> List[nodes.Node]: + def get_display_prefix(self) -> List[Node]: #: what is displayed right before the documentation entry return [] @@ -240,7 +240,7 @@ class JSConstructor(JSCallable): allow_nesting = True - def get_display_prefix(self) -> List[nodes.Node]: + def get_display_prefix(self) -> List[Node]: return [addnodes.desc_sig_keyword('class', 'class'), addnodes.desc_sig_space()]