mirror of
https://github.com/sphinx-doc/sphinx.git
synced 2025-02-25 18:55:22 -06:00
Merge pull request #9695 from jakobandersen/js_nodes
JS, use more desc_sig_* nodes
This commit is contained in:
Jakob Lykke Andersen
GitHub
commit
c922189920
8
CHANGES
8
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
|
||||
----------
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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 @@ class JSObject(ObjectDescription[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 @@ class JSObject(ObjectDescription[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):
|
||||
"""
|
||||
|
||||
@ -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]
|
||||
|
||||
@ -15,7 +15,8 @@ from docutils import nodes
|
||||
|
||||
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)])
|
||||
|
||||
@ -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):
|
||||
|
||||
Loading…
Reference in New Issue
Block a user