diff --git a/CHANGES b/CHANGES index 356cf05c961..fe8c0606d01 100644 --- a/CHANGES +++ b/CHANGES @@ -17,6 +17,8 @@ Incompatible changes :confval:`autosummary_generate_overwrite` to change the behavior * #5923: autodoc: the members of ``object`` class are not documented by default when ``:inherited-members:`` and ``:special-members:`` are given. +* #6417: py domain: doctree of desc_parameterlist has been changed. The + argument names, annotations and default values are wrapped with inline node Deprecated ---------- @@ -32,6 +34,7 @@ Features added not to document inherited members of the class and uppers * #6558: glossary: emit a warning for duplicated glossary entry * #6558: std domain: emit a warning for duplicated generic objects +* #6417: py domain: Allow to make a style for arguments of functions and methods Bugs fixed ---------- diff --git a/sphinx/domains/python.py b/sphinx/domains/python.py index f23c5025614..723c505c01a 100644 --- a/sphinx/domains/python.py +++ b/sphinx/domains/python.py @@ -26,6 +26,7 @@ from sphinx.domains import Domain, ObjType, Index, IndexEntry from sphinx.environment import BuildEnvironment from sphinx.locale import _, __ +from sphinx.pycode.function import Signature from sphinx.roles import XRefRole from sphinx.util import logging from sphinx.util.docfields import Field, GroupedField, TypedField @@ -62,6 +63,31 @@ } +def _parse_arglist(arglist: str) -> addnodes.desc_parameterlist: + """Parse a list of arguments using python parser""" + params = addnodes.desc_parameterlist(arglist) + sig = Signature('(%s)' % arglist) + for param in sig.parameters.values(): + node = addnodes.desc_parameter() + if param.kind == param.VAR_POSITIONAL: + node += nodes.inline('', '*' + param.name, classes=['argument']) + elif param.kind == param.VAR_KEYWORD: + node += nodes.inline('', '**' + param.name, classes=['argument']) + else: + node += nodes.inline('', param.name, classes=['argument']) + + if param.annotation is not param.empty: + node += nodes.Text(': ') + node += nodes.inline('', param.annotation, classes=['annotation']) + if param.default is not param.empty: + node += nodes.Text(' = ') + node += nodes.inline('', param.default, classes=['default_value']) + + params += node + + return params + + def _pseudo_parse_arglist(signode: desc_signature, arglist: str) -> None: """"Parse" a list of arguments separated by commas. @@ -284,7 +310,11 @@ def handle_signature(self, sig: str, signode: desc_signature) -> Tuple[str, str] signode += addnodes.desc_name(name, name) if arglist: - _pseudo_parse_arglist(signode, arglist) + try: + signode += _parse_arglist(arglist) + except SyntaxError: + # failed to parse arglist by python's parser + _pseudo_parse_arglist(signode, arglist) else: if self.needs_arglist(): # for callables, add an empty parameter list diff --git a/tests/test_build_html.py b/tests/test_build_html.py index 63a5948af6f..ef1a36fc853 100644 --- a/tests/test_build_html.py +++ b/tests/test_build_html.py @@ -177,7 +177,7 @@ def test_html4_output(app, status, warning): ], 'autodoc.html': [ (".//dt[@id='autodoc_target.Class']", ''), - (".//dt[@id='autodoc_target.function']/em", r'\*\*kwds'), + (".//dt[@id='autodoc_target.function']/em/span[@class='argument']", r'\*\*kwds'), (".//dd/p", r'Return spam\.'), ], 'extapi.html': [ diff --git a/tests/test_domain_py.py b/tests/test_domain_py.py index 3ff29cbb7a6..b26cf29685b 100644 --- a/tests/test_domain_py.py +++ b/tests/test_domain_py.py @@ -223,7 +223,10 @@ def test_pyfunction_signature(app): desc_content)])) assert_node(doctree[1], addnodes.desc, desctype="function", domain="py", objtype="function", noindex=False) - assert_node(doctree[1][0][1], [desc_parameterlist, desc_parameter, "name: str"]) + assert_node(doctree[1][0][1], + [desc_parameterlist, desc_parameter, ([nodes.inline, "name"], + ": ", + [nodes.inline, "str"])]) def test_optional_pyfunction_signature(app):