IntenseWebs/sphinx
3
0
Fork 0
mirror of https://github.com/sphinx-doc/sphinx.git synced 2025-02-25 18:55:22 -06:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #9672 from jakobandersen/py_nodes

Browse Source 
Py, use more desc_sig_* nodes
This commit is contained in:
Jakob Lykke Andersen 2021-10-03 10:16:27 +02:00 committed by GitHub
commit ebea4327e3
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
3 changed files with 184 additions and 105 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

7
CHANGES
View File

@ -9,6 +9,12 @@ Incompatible changes
* #9649: ``searchindex.js``: the embedded data has changed format to allow * #9649: ``searchindex.js``: the embedded data has changed format to allow
objects with the same name in different domains. objects with the same name in different domains.
* #9672: The rendering of Python domain declarations is implemented
with more docutils nodes to allow better CSS styling.
It may break existing styling.
* #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.
Deprecated Deprecated
---------- ----------
@ -22,6 +28,7 @@ Features added
* #9691: C, added new info-field ``retval`` * #9691: C, added new info-field ``retval``
for :rst:dir:`c:function` and :rst:dir:`c:macro`. for :rst:dir:`c:function` and :rst:dir:`c:macro`.
* C++, added new info-field ``retval`` for :rst:dir:`cpp:function`. * C++, added new info-field ``retval`` for :rst:dir:`cpp:function`.
* #9672: More CSS classes on Python domain descriptions
Bugs fixed Bugs fixed
---------- ----------

115
sphinx/domains/python.py
View File

@ -118,11 +118,21 @@ def _parse_annotation(annotation: str, env: BuildEnvironment = None) -> List[Nod
result.extend(unparse(node.right)) result.extend(unparse(node.right))
return result return result
elif isinstance(node, ast.BitOr): elif isinstance(node, ast.BitOr):
return [nodes.Text(' '), addnodes.desc_sig_punctuation('', '|'), nodes.Text(' ')] return [addnodes.desc_sig_space(),
addnodes.desc_sig_punctuation('', '|'),
addnodes.desc_sig_space()]
elif isinstance(node, ast.Constant): # type: ignore elif isinstance(node, ast.Constant): # type: ignore
if node.value is Ellipsis: if node.value is Ellipsis:
return [addnodes.desc_sig_punctuation('', "...")] return [addnodes.desc_sig_punctuation('', "...")]
elif isinstance(node.value, bool):
return [addnodes.desc_sig_keyword('', repr(node.value))]
elif isinstance(node.value, int):
return [addnodes.desc_sig_literal_number('', repr(node.value))]
elif isinstance(node.value, str):
return [addnodes.desc_sig_literal_string('', repr(node.value))]
else: else:
# handles None, which is further handled by type_to_xref later
# and fallback for other types that should be converted
return [nodes.Text(repr(node.value))] return [nodes.Text(repr(node.value))]
elif isinstance(node, ast.Expr): elif isinstance(node, ast.Expr):
return unparse(node.value) return unparse(node.value)
@ -137,6 +147,8 @@ def _parse_annotation(annotation: str, env: BuildEnvironment = None) -> List[Nod
for elem in node.elts: for elem in node.elts:
result.extend(unparse(elem)) result.extend(unparse(elem))
result.append(addnodes.desc_sig_punctuation('', ',')) result.append(addnodes.desc_sig_punctuation('', ','))
result.append(addnodes.desc_sig_space())
result.pop()
result.pop() result.pop()
result.append(addnodes.desc_sig_punctuation('', ']')) result.append(addnodes.desc_sig_punctuation('', ']'))
return result return result
@ -162,6 +174,8 @@ def _parse_annotation(annotation: str, env: BuildEnvironment = None) -> List[Nod
for elem in node.elts: for elem in node.elts:
result.extend(unparse(elem)) result.extend(unparse(elem))
result.append(addnodes.desc_sig_punctuation('', ',')) result.append(addnodes.desc_sig_punctuation('', ','))
result.append(addnodes.desc_sig_space())
result.pop()
result.pop() result.pop()
else: else:
result = [addnodes.desc_sig_punctuation('', '('), result = [addnodes.desc_sig_punctuation('', '('),
@ -222,13 +236,13 @@ def _parse_arglist(arglist: str, env: BuildEnvironment = None) -> addnodes.desc_
if param.annotation is not param.empty: if param.annotation is not param.empty:
children = _parse_annotation(param.annotation, env) children = _parse_annotation(param.annotation, env)
node += addnodes.desc_sig_punctuation('', ':') node += addnodes.desc_sig_punctuation('', ':')
node += nodes.Text(' ') node += addnodes.desc_sig_space()
node += addnodes.desc_sig_name('', '', *children) # type: ignore node += addnodes.desc_sig_name('', '', *children) # type: ignore
if param.default is not param.empty: if param.default is not param.empty:
if param.annotation is not param.empty: if param.annotation is not param.empty:
node += nodes.Text(' ') node += addnodes.desc_sig_space()
node += addnodes.desc_sig_operator('', '=') node += addnodes.desc_sig_operator('', '=')
node += nodes.Text(' ') node += addnodes.desc_sig_space()
else: else:
node += addnodes.desc_sig_operator('', '=') node += addnodes.desc_sig_operator('', '=')
node += nodes.inline('', param.default, classes=['default_value'], node += nodes.inline('', param.default, classes=['default_value'],
@ -418,11 +432,11 @@ class PyObject(ObjectDescription[Tuple[str, str]]):
allow_nesting = False allow_nesting = False
def get_signature_prefix(self, sig: str) -> str: def get_signature_prefix(self, sig: str) -> List[nodes.Node]:
"""May return a prefix to put before the object name in the """May return a prefix to put before the object name in the
signature. signature.
""" """
return '' return []
def needs_arglist(self) -> bool: def needs_arglist(self) -> bool:
"""May return true if an empty argument list is to be generated even if """May return true if an empty argument list is to be generated even if
@ -476,7 +490,7 @@ class PyObject(ObjectDescription[Tuple[str, str]]):
sig_prefix = self.get_signature_prefix(sig) sig_prefix = self.get_signature_prefix(sig)
if sig_prefix: if sig_prefix:
signode += addnodes.desc_annotation(sig_prefix, sig_prefix) signode += addnodes.desc_annotation(str(sig_prefix), '', *sig_prefix)
if prefix: if prefix:
signode += addnodes.desc_addname(prefix, prefix) signode += addnodes.desc_addname(prefix, prefix)
@ -507,7 +521,9 @@ class PyObject(ObjectDescription[Tuple[str, str]]):
anno = self.options.get('annotation') anno = self.options.get('annotation')
if anno: if anno:
signode += addnodes.desc_annotation(' ' + anno, ' ' + anno) signode += addnodes.desc_annotation(' ' + anno, '',
addnodes.desc_sig_space(),
nodes.Text(anno))
return fullname, prefix return fullname, prefix
@ -609,11 +625,12 @@ class PyFunction(PyObject):
'async': directives.flag, 'async': directives.flag,
}) })
def get_signature_prefix(self, sig: str) -> str: def get_signature_prefix(self, sig: str) -> List[nodes.Node]:
if 'async' in self.options: if 'async' in self.options:
return 'async ' return [addnodes.desc_sig_keyword('', 'async'),
addnodes.desc_sig_space()]
else: else:
return '' return []
def needs_arglist(self) -> bool: def needs_arglist(self) -> bool:
return True return True
@ -670,11 +687,17 @@ class PyVariable(PyObject):
typ = self.options.get('type') typ = self.options.get('type')
if typ: if typ:
annotations = _parse_annotation(typ, self.env) annotations = _parse_annotation(typ, self.env)
signode += addnodes.desc_annotation(typ, '', nodes.Text(': '), *annotations) signode += addnodes.desc_annotation(typ, '',
addnodes.desc_sig_punctuation('', ':'),
addnodes.desc_sig_space(), *annotations)
value = self.options.get('value') value = self.options.get('value')
if value: if value:
signode += addnodes.desc_annotation(value, ' = ' + value) signode += addnodes.desc_annotation(value, '',
addnodes.desc_sig_space(),
addnodes.desc_sig_punctuation('', '='),
addnodes.desc_sig_space(),
nodes.Text(value))
return fullname, prefix return fullname, prefix
@ -698,11 +721,12 @@ class PyClasslike(PyObject):
allow_nesting = True allow_nesting = True
def get_signature_prefix(self, sig: str) -> str: def get_signature_prefix(self, sig: str) -> List[nodes.Node]:
if 'final' in self.options: if 'final' in self.options:
return 'final %s ' % self.objtype return [nodes.Text('final'), addnodes.desc_sig_space(),
nodes.Text(self.objtype), addnodes.desc_sig_space()]
else: else:
return '%s ' % self.objtype return [nodes.Text(self.objtype), addnodes.desc_sig_space()]
def get_index_text(self, modname: str, name_cls: Tuple[str, str]) -> str: def get_index_text(self, modname: str, name_cls: Tuple[str, str]) -> str:
if self.objtype == 'class': if self.objtype == 'class':
@ -734,25 +758,27 @@ class PyMethod(PyObject):
else: else:
return True return True
def get_signature_prefix(self, sig: str) -> str: def get_signature_prefix(self, sig: str) -> List[nodes.Node]:
prefix = [] prefix: List[nodes.Node] = []
if 'final' in self.options: if 'final' in self.options:
prefix.append('final') prefix.append(nodes.Text('final'))
prefix.append(addnodes.desc_sig_space())
if 'abstractmethod' in self.options: if 'abstractmethod' in self.options:
prefix.append('abstract') prefix.append(nodes.Text('abstract'))
prefix.append(addnodes.desc_sig_space())
if 'async' in self.options: if 'async' in self.options:
prefix.append('async') prefix.append(nodes.Text('async'))
prefix.append(addnodes.desc_sig_space())
if 'classmethod' in self.options: if 'classmethod' in self.options:
prefix.append('classmethod') prefix.append(nodes.Text('classmethod'))
prefix.append(addnodes.desc_sig_space())
if 'property' in self.options: if 'property' in self.options:
prefix.append('property') prefix.append(nodes.Text('property'))
prefix.append(addnodes.desc_sig_space())
if 'staticmethod' in self.options: if 'staticmethod' in self.options:
prefix.append('static') prefix.append(nodes.Text('static'))
prefix.append(addnodes.desc_sig_space())
if prefix: return prefix
return ' '.join(prefix) + ' '
else:
return ''
def get_index_text(self, modname: str, name_cls: Tuple[str, str]) -> str: def get_index_text(self, modname: str, name_cls: Tuple[str, str]) -> str:
name, cls = name_cls name, cls = name_cls
@ -831,11 +857,18 @@ class PyAttribute(PyObject):
typ = self.options.get('type') typ = self.options.get('type')
if typ: if typ:
annotations = _parse_annotation(typ, self.env) annotations = _parse_annotation(typ, self.env)
signode += addnodes.desc_annotation(typ, '', nodes.Text(': '), *annotations) signode += addnodes.desc_annotation(typ, '',
addnodes.desc_sig_punctuation('', ':'),
addnodes.desc_sig_space(),
*annotations)
value = self.options.get('value') value = self.options.get('value')
if value: if value:
signode += addnodes.desc_annotation(value, ' = ' + value) signode += addnodes.desc_annotation(value, '',
addnodes.desc_sig_space(),
addnodes.desc_sig_punctuation('', '='),
addnodes.desc_sig_space(),
nodes.Text(value))
return fullname, prefix return fullname, prefix
@ -870,19 +903,25 @@ class PyProperty(PyObject):
typ = self.options.get('type') typ = self.options.get('type')
if typ: if typ:
annotations = _parse_annotation(typ, self.env) annotations = _parse_annotation(typ, self.env)
signode += addnodes.desc_annotation(typ, '', nodes.Text(': '), *annotations) signode += addnodes.desc_annotation(typ, '',
addnodes.desc_sig_punctuation('', ':'),
addnodes.desc_sig_space(),
*annotations)
return fullname, prefix return fullname, prefix
def get_signature_prefix(self, sig: str) -> str: def get_signature_prefix(self, sig: str) -> List[nodes.Node]:
prefix = [] prefix: List[nodes.Node] = []
if 'abstractmethod' in self.options: if 'abstractmethod' in self.options:
prefix.append('abstract') prefix.append(nodes.Text('abstract'))
prefix.append(addnodes.desc_sig_space())
if 'classmethod' in self.options: if 'classmethod' in self.options:
prefix.append('class') prefix.append(nodes.Text('class'))
prefix.append(addnodes.desc_sig_space())
prefix.append('property') prefix.append(nodes.Text('property'))
return ' '.join(prefix) + ' ' prefix.append(addnodes.desc_sig_space())
return prefix
def get_index_text(self, modname: str, name_cls: Tuple[str, str]) -> str: def get_index_text(self, modname: str, name_cls: Tuple[str, str]) -> str:
name, cls = name_cls name, cls = name_cls

147
tests/test_domain_py.py
View File

@ -18,8 +18,10 @@ from docutils import nodes
from sphinx import addnodes from sphinx import addnodes
from sphinx.addnodes import (desc, desc_addname, desc_annotation, desc_content, desc_name, from sphinx.addnodes import (desc, desc_addname, desc_annotation, desc_content, desc_name,
desc_optional, desc_parameter, desc_parameterlist, desc_returns, desc_optional, desc_parameter, desc_parameterlist, desc_returns,
desc_sig_name, desc_sig_operator, desc_sig_punctuation, desc_sig_keyword, desc_sig_literal_number,
desc_signature, pending_xref) desc_sig_literal_string, desc_sig_name, desc_sig_operator,
desc_sig_punctuation, desc_sig_space, desc_signature,
pending_xref)
from sphinx.domains import IndexEntry from sphinx.domains import IndexEntry
from sphinx.domains.python import (PythonDomain, PythonModuleIndex, _parse_annotation, from sphinx.domains.python import (PythonDomain, PythonModuleIndex, _parse_annotation,
_pseudo_parse_arglist, py_sig_re) _pseudo_parse_arglist, py_sig_re)
@ -291,6 +293,7 @@ def test_parse_annotation(app):
[desc_sig_punctuation, "["], [desc_sig_punctuation, "["],
[pending_xref, "int"], [pending_xref, "int"],
[desc_sig_punctuation, ","], [desc_sig_punctuation, ","],
desc_sig_space,
[pending_xref, "int"], [pending_xref, "int"],
[desc_sig_punctuation, "]"])) [desc_sig_punctuation, "]"]))
@ -306,18 +309,22 @@ def test_parse_annotation(app):
[desc_sig_punctuation, "["], [desc_sig_punctuation, "["],
[pending_xref, "int"], [pending_xref, "int"],
[desc_sig_punctuation, ","], [desc_sig_punctuation, ","],
desc_sig_space,
[desc_sig_punctuation, "..."], [desc_sig_punctuation, "..."],
[desc_sig_punctuation, "]"])) [desc_sig_punctuation, "]"]))
doctree = _parse_annotation("Callable[[int, int], int]", app.env) doctree = _parse_annotation("Callable[[int, int], int]", app.env)
print(doctree)
assert_node(doctree, ([pending_xref, "Callable"], assert_node(doctree, ([pending_xref, "Callable"],
[desc_sig_punctuation, "["], [desc_sig_punctuation, "["],
[desc_sig_punctuation, "["], [desc_sig_punctuation, "["],
[pending_xref, "int"], [pending_xref, "int"],
[desc_sig_punctuation, ","], [desc_sig_punctuation, ","],
desc_sig_space,
[pending_xref, "int"], [pending_xref, "int"],
[desc_sig_punctuation, "]"], [desc_sig_punctuation, "]"],
[desc_sig_punctuation, ","], [desc_sig_punctuation, ","],
desc_sig_space,
[pending_xref, "int"], [pending_xref, "int"],
[desc_sig_punctuation, "]"])) [desc_sig_punctuation, "]"]))
@ -327,6 +334,7 @@ def test_parse_annotation(app):
[desc_sig_punctuation, "["], [desc_sig_punctuation, "["],
[desc_sig_punctuation, "]"], [desc_sig_punctuation, "]"],
[desc_sig_punctuation, ","], [desc_sig_punctuation, ","],
desc_sig_space,
[pending_xref, "int"], [pending_xref, "int"],
[desc_sig_punctuation, "]"])) [desc_sig_punctuation, "]"]))
@ -347,19 +355,22 @@ def test_parse_annotation_Literal(app):
doctree = _parse_annotation("Literal[True, False]", app.env) doctree = _parse_annotation("Literal[True, False]", app.env)
assert_node(doctree, ([pending_xref, "Literal"], assert_node(doctree, ([pending_xref, "Literal"],
[desc_sig_punctuation, "["], [desc_sig_punctuation, "["],
"True", [desc_sig_keyword, "True"],
[desc_sig_punctuation, ","], [desc_sig_punctuation, ","],
"False", desc_sig_space,
[desc_sig_keyword, "False"],
[desc_sig_punctuation, "]"])) [desc_sig_punctuation, "]"]))
doctree = _parse_annotation("typing.Literal[0, 1, 'abc']", app.env) doctree = _parse_annotation("typing.Literal[0, 1, 'abc']", app.env)
assert_node(doctree, ([pending_xref, "typing.Literal"], assert_node(doctree, ([pending_xref, "typing.Literal"],
[desc_sig_punctuation, "["], [desc_sig_punctuation, "["],
"0", [desc_sig_literal_number, "0"],
[desc_sig_punctuation, ","], [desc_sig_punctuation, ","],
"1", desc_sig_space,
[desc_sig_literal_number, "1"],
[desc_sig_punctuation, ","], [desc_sig_punctuation, ","],
"'abc'", desc_sig_space,
[desc_sig_literal_string, "'abc'"],
[desc_sig_punctuation, "]"])) [desc_sig_punctuation, "]"]))
@ -376,7 +387,7 @@ def test_pyfunction_signature(app):
assert_node(doctree[1][0][1], assert_node(doctree[1][0][1],
[desc_parameterlist, desc_parameter, ([desc_sig_name, "name"], [desc_parameterlist, desc_parameter, ([desc_sig_name, "name"],
[desc_sig_punctuation, ":"], [desc_sig_punctuation, ":"],
" ", desc_sig_space,
[nodes.inline, pending_xref, "str"])]) [nodes.inline, pending_xref, "str"])])
@ -394,7 +405,7 @@ def test_pyfunction_signature_full(app):
assert_node(doctree[1][0][1], assert_node(doctree[1][0][1],
[desc_parameterlist, ([desc_parameter, ([desc_sig_name, "a"], [desc_parameterlist, ([desc_parameter, ([desc_sig_name, "a"],
[desc_sig_punctuation, ":"], [desc_sig_punctuation, ":"],
" ", desc_sig_space,
[desc_sig_name, pending_xref, "str"])], [desc_sig_name, pending_xref, "str"])],
[desc_parameter, ([desc_sig_name, "b"], [desc_parameter, ([desc_sig_name, "b"],
[desc_sig_operator, "="], [desc_sig_operator, "="],
@ -402,28 +413,28 @@ def test_pyfunction_signature_full(app):
[desc_parameter, ([desc_sig_operator, "*"], [desc_parameter, ([desc_sig_operator, "*"],
[desc_sig_name, "args"], [desc_sig_name, "args"],
[desc_sig_punctuation, ":"], [desc_sig_punctuation, ":"],
" ", desc_sig_space,
[desc_sig_name, pending_xref, "str"])], [desc_sig_name, pending_xref, "str"])],
[desc_parameter, ([desc_sig_name, "c"], [desc_parameter, ([desc_sig_name, "c"],
[desc_sig_punctuation, ":"], [desc_sig_punctuation, ":"],
" ", desc_sig_space,
[desc_sig_name, pending_xref, "bool"], [desc_sig_name, pending_xref, "bool"],
" ", desc_sig_space,
[desc_sig_operator, "="], [desc_sig_operator, "="],
" ", desc_sig_space,
[nodes.inline, "True"])], [nodes.inline, "True"])],
[desc_parameter, ([desc_sig_name, "d"], [desc_parameter, ([desc_sig_name, "d"],
[desc_sig_punctuation, ":"], [desc_sig_punctuation, ":"],
" ", desc_sig_space,
[desc_sig_name, pending_xref, "tuple"], [desc_sig_name, pending_xref, "tuple"],
" ", desc_sig_space,
[desc_sig_operator, "="], [desc_sig_operator, "="],
" ", desc_sig_space,
[nodes.inline, "(1, 2)"])], [nodes.inline, "(1, 2)"])],
[desc_parameter, ([desc_sig_operator, "**"], [desc_parameter, ([desc_sig_operator, "**"],
[desc_sig_name, "kwargs"], [desc_sig_name, "kwargs"],
[desc_sig_punctuation, ":"], [desc_sig_punctuation, ":"],
" ", desc_sig_space,
[desc_sig_name, pending_xref, "str"])])]) [desc_sig_name, pending_xref, "str"])])])
@ -482,11 +493,11 @@ def test_pyfunction_with_union_type_operator(app):
assert_node(doctree[1][0][1], assert_node(doctree[1][0][1],
[desc_parameterlist, ([desc_parameter, ([desc_sig_name, "age"], [desc_parameterlist, ([desc_parameter, ([desc_sig_name, "age"],
[desc_sig_punctuation, ":"], [desc_sig_punctuation, ":"],
" ", desc_sig_space,
[desc_sig_name, ([pending_xref, "int"], [desc_sig_name, ([pending_xref, "int"],
" ", desc_sig_space,
[desc_sig_punctuation, "|"], [desc_sig_punctuation, "|"],
" ", desc_sig_space,
[pending_xref, "None"])])])]) [pending_xref, "None"])])])])
@ -510,7 +521,7 @@ def test_pyexception_signature(app):
text = ".. py:exception:: builtins.IOError" text = ".. py:exception:: builtins.IOError"
doctree = restructuredtext.parse(app, text) doctree = restructuredtext.parse(app, text)
assert_node(doctree, (addnodes.index, assert_node(doctree, (addnodes.index,
[desc, ([desc_signature, ([desc_annotation, "exception "], [desc, ([desc_signature, ([desc_annotation, ('exception', desc_sig_space)],
[desc_addname, "builtins."], [desc_addname, "builtins."],
[desc_name, "IOError"])], [desc_name, "IOError"])],
desc_content)])) desc_content)]))
@ -525,9 +536,15 @@ def test_pydata_signature(app):
doctree = restructuredtext.parse(app, text) doctree = restructuredtext.parse(app, text)
assert_node(doctree, (addnodes.index, assert_node(doctree, (addnodes.index,
[desc, ([desc_signature, ([desc_name, "version"], [desc, ([desc_signature, ([desc_name, "version"],
[desc_annotation, (": ", [desc_annotation, ([desc_sig_punctuation, ':'],
desc_sig_space,
[pending_xref, "int"])], [pending_xref, "int"])],
[desc_annotation, " = 1"])], [desc_annotation, (
desc_sig_space,
[desc_sig_punctuation, '='],
desc_sig_space,
"1")]
)],
desc_content)])) desc_content)]))
assert_node(doctree[1], addnodes.desc, desctype="data", assert_node(doctree[1], addnodes.desc, desctype="data",
domain="py", objtype="data", noindex=False) domain="py", objtype="data", noindex=False)
@ -539,7 +556,8 @@ def test_pydata_signature_old(app):
doctree = restructuredtext.parse(app, text) doctree = restructuredtext.parse(app, text)
assert_node(doctree, (addnodes.index, assert_node(doctree, (addnodes.index,
[desc, ([desc_signature, ([desc_name, "version"], [desc, ([desc_signature, ([desc_name, "version"],
[desc_annotation, " = 1"])], [desc_annotation, (desc_sig_space,
"= 1")])],
desc_content)])) desc_content)]))
assert_node(doctree[1], addnodes.desc, desctype="data", assert_node(doctree[1], addnodes.desc, desctype="data",
domain="py", objtype="data", noindex=False) domain="py", objtype="data", noindex=False)
@ -551,11 +569,12 @@ def test_pydata_with_union_type_operator(app):
doctree = restructuredtext.parse(app, text) doctree = restructuredtext.parse(app, text)
assert_node(doctree[1][0], assert_node(doctree[1][0],
([desc_name, "version"], ([desc_name, "version"],
[desc_annotation, (": ", [desc_annotation, ([desc_sig_punctuation, ':'],
desc_sig_space,
[pending_xref, "int"], [pending_xref, "int"],
" ", desc_sig_space,
[desc_sig_punctuation, "|"], [desc_sig_punctuation, "|"],
" ", desc_sig_space,
[pending_xref, "str"])])) [pending_xref, "str"])]))
@ -566,7 +585,7 @@ def test_pyobject_prefix(app):
" .. py:method:: FooBar.say") " .. py:method:: FooBar.say")
doctree = restructuredtext.parse(app, text) doctree = restructuredtext.parse(app, text)
assert_node(doctree, (addnodes.index, assert_node(doctree, (addnodes.index,
[desc, ([desc_signature, ([desc_annotation, "class "], [desc, ([desc_signature, ([desc_annotation, ('class', desc_sig_space)],
[desc_name, "Foo"])], [desc_name, "Foo"])],
[desc_content, (addnodes.index, [desc_content, (addnodes.index,
desc, desc,
@ -587,10 +606,11 @@ def test_pydata(app):
addnodes.index, addnodes.index,
[desc, ([desc_signature, ([desc_addname, "example."], [desc, ([desc_signature, ([desc_addname, "example."],
[desc_name, "var"], [desc_name, "var"],
[desc_annotation, (": ", [desc_annotation, ([desc_sig_punctuation, ':'],
desc_sig_space,
[pending_xref, "int"])])], [pending_xref, "int"])])],
[desc_content, ()])])) [desc_content, ()])]))
assert_node(doctree[3][0][2][1], pending_xref, **{"py:module": "example"}) assert_node(doctree[3][0][2][2], pending_xref, **{"py:module": "example"})
assert 'example.var' in domain.objects assert 'example.var' in domain.objects
assert domain.objects['example.var'] == ('index', 'example.var', 'data', False) assert domain.objects['example.var'] == ('index', 'example.var', 'data', False)
@ -609,7 +629,8 @@ def test_pyfunction(app):
nodes.target, nodes.target,
addnodes.index, addnodes.index,
addnodes.index, addnodes.index,
[desc, ([desc_signature, ([desc_annotation, "async "], [desc, ([desc_signature, ([desc_annotation, ([desc_sig_keyword, 'async'],
desc_sig_space)],
[desc_addname, "example."], [desc_addname, "example."],
[desc_name, "func2"], [desc_name, "func2"],
[desc_parameterlist, ()])], [desc_parameterlist, ()])],
@ -634,11 +655,14 @@ def test_pyclass_options(app):
domain = app.env.get_domain('py') domain = app.env.get_domain('py')
doctree = restructuredtext.parse(app, text) doctree = restructuredtext.parse(app, text)
assert_node(doctree, (addnodes.index, assert_node(doctree, (addnodes.index,
[desc, ([desc_signature, ([desc_annotation, "class "], [desc, ([desc_signature, ([desc_annotation, ("class", desc_sig_space)],
[desc_name, "Class1"])], [desc_name, "Class1"])],
[desc_content, ()])], [desc_content, ()])],
addnodes.index, addnodes.index,
[desc, ([desc_signature, ([desc_annotation, "final class "], [desc, ([desc_signature, ([desc_annotation, ("final",
desc_sig_space,
"class",
desc_sig_space)],
[desc_name, "Class2"])], [desc_name, "Class2"])],
[desc_content, ()])])) [desc_content, ()])]))
@ -674,7 +698,7 @@ def test_pymethod_options(app):
domain = app.env.get_domain('py') domain = app.env.get_domain('py')
doctree = restructuredtext.parse(app, text) doctree = restructuredtext.parse(app, text)
assert_node(doctree, (addnodes.index, assert_node(doctree, (addnodes.index,
[desc, ([desc_signature, ([desc_annotation, "class "], [desc, ([desc_signature, ([desc_annotation, ("class", desc_sig_space)],
[desc_name, "Class"])], [desc_name, "Class"])],
[desc_content, (addnodes.index, [desc_content, (addnodes.index,
desc, desc,
@ -703,7 +727,7 @@ def test_pymethod_options(app):
# :classmethod: # :classmethod:
assert_node(doctree[1][1][2], addnodes.index, assert_node(doctree[1][1][2], addnodes.index,
entries=[('single', 'meth2() (Class class method)', 'Class.meth2', '', None)]) entries=[('single', 'meth2() (Class class method)', 'Class.meth2', '', None)])
assert_node(doctree[1][1][3], ([desc_signature, ([desc_annotation, "classmethod "], assert_node(doctree[1][1][3], ([desc_signature, ([desc_annotation, ("classmethod", desc_sig_space)],
[desc_name, "meth2"], [desc_name, "meth2"],
[desc_parameterlist, ()])], [desc_parameterlist, ()])],
[desc_content, ()])) [desc_content, ()]))
@ -713,7 +737,7 @@ def test_pymethod_options(app):
# :staticmethod: # :staticmethod:
assert_node(doctree[1][1][4], addnodes.index, assert_node(doctree[1][1][4], addnodes.index,
entries=[('single', 'meth3() (Class static method)', 'Class.meth3', '', None)]) entries=[('single', 'meth3() (Class static method)', 'Class.meth3', '', None)])
assert_node(doctree[1][1][5], ([desc_signature, ([desc_annotation, "static "], assert_node(doctree[1][1][5], ([desc_signature, ([desc_annotation, ("static", desc_sig_space)],
[desc_name, "meth3"], [desc_name, "meth3"],
[desc_parameterlist, ()])], [desc_parameterlist, ()])],
[desc_content, ()])) [desc_content, ()]))
@ -723,7 +747,7 @@ def test_pymethod_options(app):
# :async: # :async:
assert_node(doctree[1][1][6], addnodes.index, assert_node(doctree[1][1][6], addnodes.index,
entries=[('single', 'meth4() (Class method)', 'Class.meth4', '', None)]) entries=[('single', 'meth4() (Class method)', 'Class.meth4', '', None)])
assert_node(doctree[1][1][7], ([desc_signature, ([desc_annotation, "async "], assert_node(doctree[1][1][7], ([desc_signature, ([desc_annotation, ("async", desc_sig_space)],
[desc_name, "meth4"], [desc_name, "meth4"],
[desc_parameterlist, ()])], [desc_parameterlist, ()])],
[desc_content, ()])) [desc_content, ()]))
@ -733,7 +757,7 @@ def test_pymethod_options(app):
# :property: # :property:
assert_node(doctree[1][1][8], addnodes.index, assert_node(doctree[1][1][8], addnodes.index,
entries=[('single', 'meth5() (Class property)', 'Class.meth5', '', None)]) entries=[('single', 'meth5() (Class property)', 'Class.meth5', '', None)])
assert_node(doctree[1][1][9], ([desc_signature, ([desc_annotation, "property "], assert_node(doctree[1][1][9], ([desc_signature, ([desc_annotation, ("property", desc_sig_space)],
[desc_name, "meth5"])], [desc_name, "meth5"])],
[desc_content, ()])) [desc_content, ()]))
assert 'Class.meth5' in domain.objects assert 'Class.meth5' in domain.objects
@ -742,7 +766,7 @@ def test_pymethod_options(app):
# :abstractmethod: # :abstractmethod:
assert_node(doctree[1][1][10], addnodes.index, assert_node(doctree[1][1][10], addnodes.index,
entries=[('single', 'meth6() (Class method)', 'Class.meth6', '', None)]) entries=[('single', 'meth6() (Class method)', 'Class.meth6', '', None)])
assert_node(doctree[1][1][11], ([desc_signature, ([desc_annotation, "abstract "], assert_node(doctree[1][1][11], ([desc_signature, ([desc_annotation, ("abstract", desc_sig_space)],
[desc_name, "meth6"], [desc_name, "meth6"],
[desc_parameterlist, ()])], [desc_parameterlist, ()])],
[desc_content, ()])) [desc_content, ()]))
@ -752,7 +776,7 @@ def test_pymethod_options(app):
# :final: # :final:
assert_node(doctree[1][1][12], addnodes.index, assert_node(doctree[1][1][12], addnodes.index,
entries=[('single', 'meth7() (Class method)', 'Class.meth7', '', None)]) entries=[('single', 'meth7() (Class method)', 'Class.meth7', '', None)])
assert_node(doctree[1][1][13], ([desc_signature, ([desc_annotation, "final "], assert_node(doctree[1][1][13], ([desc_signature, ([desc_annotation, ("final", desc_sig_space)],
[desc_name, "meth7"], [desc_name, "meth7"],
[desc_parameterlist, ()])], [desc_parameterlist, ()])],
[desc_content, ()])) [desc_content, ()]))
@ -767,13 +791,13 @@ def test_pyclassmethod(app):
domain = app.env.get_domain('py') domain = app.env.get_domain('py')
doctree = restructuredtext.parse(app, text) doctree = restructuredtext.parse(app, text)
assert_node(doctree, (addnodes.index, assert_node(doctree, (addnodes.index,
[desc, ([desc_signature, ([desc_annotation, "class "], [desc, ([desc_signature, ([desc_annotation, ("class", desc_sig_space)],
[desc_name, "Class"])], [desc_name, "Class"])],
[desc_content, (addnodes.index, [desc_content, (addnodes.index,
desc)])])) desc)])]))
assert_node(doctree[1][1][0], addnodes.index, assert_node(doctree[1][1][0], addnodes.index,
entries=[('single', 'meth() (Class class method)', 'Class.meth', '', None)]) entries=[('single', 'meth() (Class class method)', 'Class.meth', '', None)])
assert_node(doctree[1][1][1], ([desc_signature, ([desc_annotation, "classmethod "], assert_node(doctree[1][1][1], ([desc_signature, ([desc_annotation, ("classmethod", desc_sig_space)],
[desc_name, "meth"], [desc_name, "meth"],
[desc_parameterlist, ()])], [desc_parameterlist, ()])],
[desc_content, ()])) [desc_content, ()]))
@ -788,13 +812,13 @@ def test_pystaticmethod(app):
domain = app.env.get_domain('py') domain = app.env.get_domain('py')
doctree = restructuredtext.parse(app, text) doctree = restructuredtext.parse(app, text)
assert_node(doctree, (addnodes.index, assert_node(doctree, (addnodes.index,
[desc, ([desc_signature, ([desc_annotation, "class "], [desc, ([desc_signature, ([desc_annotation, ("class", desc_sig_space)],
[desc_name, "Class"])], [desc_name, "Class"])],
[desc_content, (addnodes.index, [desc_content, (addnodes.index,
desc)])])) desc)])]))
assert_node(doctree[1][1][0], addnodes.index, assert_node(doctree[1][1][0], addnodes.index,
entries=[('single', 'meth() (Class static method)', 'Class.meth', '', None)]) entries=[('single', 'meth() (Class static method)', 'Class.meth', '', None)])
assert_node(doctree[1][1][1], ([desc_signature, ([desc_annotation, "static "], assert_node(doctree[1][1][1], ([desc_signature, ([desc_annotation, ("static", desc_sig_space)],
[desc_name, "meth"], [desc_name, "meth"],
[desc_parameterlist, ()])], [desc_parameterlist, ()])],
[desc_content, ()])) [desc_content, ()]))
@ -811,22 +835,27 @@ def test_pyattribute(app):
domain = app.env.get_domain('py') domain = app.env.get_domain('py')
doctree = restructuredtext.parse(app, text) doctree = restructuredtext.parse(app, text)
assert_node(doctree, (addnodes.index, assert_node(doctree, (addnodes.index,
[desc, ([desc_signature, ([desc_annotation, "class "], [desc, ([desc_signature, ([desc_annotation, ("class", desc_sig_space)],
[desc_name, "Class"])], [desc_name, "Class"])],
[desc_content, (addnodes.index, [desc_content, (addnodes.index,
desc)])])) desc)])]))
assert_node(doctree[1][1][0], addnodes.index, assert_node(doctree[1][1][0], addnodes.index,
entries=[('single', 'attr (Class attribute)', 'Class.attr', '', None)]) entries=[('single', 'attr (Class attribute)', 'Class.attr', '', None)])
assert_node(doctree[1][1][1], ([desc_signature, ([desc_name, "attr"], assert_node(doctree[1][1][1], ([desc_signature, ([desc_name, "attr"],
[desc_annotation, (": ", [desc_annotation, ([desc_sig_punctuation, ':'],
desc_sig_space,
[pending_xref, "Optional"], [pending_xref, "Optional"],
[desc_sig_punctuation, "["], [desc_sig_punctuation, "["],
[pending_xref, "str"], [pending_xref, "str"],
[desc_sig_punctuation, "]"])], [desc_sig_punctuation, "]"])],
[desc_annotation, " = ''"])], [desc_annotation, (desc_sig_space,
[desc_sig_punctuation, '='],
desc_sig_space,
"''")]
)],
[desc_content, ()])) [desc_content, ()]))
assert_node(doctree[1][1][1][0][1][1], pending_xref, **{"py:class": "Class"}) assert_node(doctree[1][1][1][0][1][2], pending_xref, **{"py:class": "Class"})
assert_node(doctree[1][1][1][0][1][3], pending_xref, **{"py:class": "Class"}) assert_node(doctree[1][1][1][0][1][4], pending_xref, **{"py:class": "Class"})
assert 'Class.attr' in domain.objects assert 'Class.attr' in domain.objects
assert domain.objects['Class.attr'] == ('index', 'Class.attr', 'attribute', False) assert domain.objects['Class.attr'] == ('index', 'Class.attr', 'attribute', False)
@ -844,7 +873,7 @@ def test_pyproperty(app):
domain = app.env.get_domain('py') domain = app.env.get_domain('py')
doctree = restructuredtext.parse(app, text) doctree = restructuredtext.parse(app, text)
assert_node(doctree, (addnodes.index, assert_node(doctree, (addnodes.index,
[desc, ([desc_signature, ([desc_annotation, "class "], [desc, ([desc_signature, ([desc_annotation, ("class", desc_sig_space)],
[desc_name, "Class"])], [desc_name, "Class"])],
[desc_content, (addnodes.index, [desc_content, (addnodes.index,
desc, desc,
@ -852,16 +881,20 @@ def test_pyproperty(app):
desc)])])) desc)])]))
assert_node(doctree[1][1][0], addnodes.index, assert_node(doctree[1][1][0], addnodes.index,
entries=[('single', 'prop1 (Class property)', 'Class.prop1', '', None)]) entries=[('single', 'prop1 (Class property)', 'Class.prop1', '', None)])
assert_node(doctree[1][1][1], ([desc_signature, ([desc_annotation, "abstract property "], assert_node(doctree[1][1][1], ([desc_signature, ([desc_annotation, ("abstract", desc_sig_space,
"property", desc_sig_space)],
[desc_name, "prop1"], [desc_name, "prop1"],
[desc_annotation, (": ", [desc_annotation, ([desc_sig_punctuation, ':'],
desc_sig_space,
[pending_xref, "str"])])], [pending_xref, "str"])])],
[desc_content, ()])) [desc_content, ()]))
assert_node(doctree[1][1][2], addnodes.index, assert_node(doctree[1][1][2], addnodes.index,
entries=[('single', 'prop2 (Class property)', 'Class.prop2', '', None)]) entries=[('single', 'prop2 (Class property)', 'Class.prop2', '', None)])
assert_node(doctree[1][1][3], ([desc_signature, ([desc_annotation, "class property "], assert_node(doctree[1][1][3], ([desc_signature, ([desc_annotation, ("class", desc_sig_space,
"property", desc_sig_space)],
[desc_name, "prop2"], [desc_name, "prop2"],
[desc_annotation, (": ", [desc_annotation, ([desc_sig_punctuation, ':'],
desc_sig_space,
[pending_xref, "str"])])], [pending_xref, "str"])])],
[desc_content, ()])) [desc_content, ()]))
assert 'Class.prop1' in domain.objects assert 'Class.prop1' in domain.objects
@ -906,7 +939,7 @@ def test_canonical(app):
domain = app.env.get_domain('py') domain = app.env.get_domain('py')
doctree = restructuredtext.parse(app, text) doctree = restructuredtext.parse(app, text)
assert_node(doctree, (addnodes.index, assert_node(doctree, (addnodes.index,
[desc, ([desc_signature, ([desc_annotation, "class "], [desc, ([desc_signature, ([desc_annotation, ("class", desc_sig_space)],
[desc_addname, "io."], [desc_addname, "io."],
[desc_name, "StringIO"])], [desc_name, "StringIO"])],
desc_content)])) desc_content)]))
@ -964,7 +997,7 @@ def test_info_field_list(app):
assert_node(doctree, (nodes.target, assert_node(doctree, (nodes.target,
addnodes.index, addnodes.index,
addnodes.index, addnodes.index,
[desc, ([desc_signature, ([desc_annotation, "class "], [desc, ([desc_signature, ([desc_annotation, ("class", desc_sig_space)],
[desc_addname, "example."], [desc_addname, "example."],
[desc_name, "Class"])], [desc_name, "Class"])],
[desc_content, nodes.field_list, nodes.field])])) [desc_content, nodes.field_list, nodes.field])]))
@ -1055,7 +1088,7 @@ def test_info_field_list_piped_type(app):
(nodes.target, (nodes.target,
addnodes.index, addnodes.index,
addnodes.index, addnodes.index,
[desc, ([desc_signature, ([desc_annotation, "class "], [desc, ([desc_signature, ([desc_annotation, ("class", desc_sig_space)],
[desc_addname, "example."], [desc_addname, "example."],
[desc_name, "Class"])], [desc_name, "Class"])],
[desc_content, nodes.field_list, nodes.field, (nodes.field_name, [desc_content, nodes.field_list, nodes.field, (nodes.field_name,