Support annotations and default values in _pseudo_parse_arglist (#13536)

Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com>

Author: koyuki7w

sphinx/domains/javascript.py

@@ -137,8 +137,9 @@ def handle_signature(self, sig: str, signode: desc_signature) -> tuple[str, str]
                 _pseudo_parse_arglist(
                     signode,
                     arglist,
-                    multi_line_parameter_list,
-                    trailing_comma,
+                    multi_line_parameter_list=multi_line_parameter_list,
+                    trailing_comma=trailing_comma,
+                    env=self.env,
                 )
         return fullname, prefix
 

sphinx/domains/python/_annotations.py

@@ -552,15 +552,18 @@ def _keyword_only_separator() -> addnodes.desc_parameter:
 def _pseudo_parse_arglist(
     signode: desc_signature,
     arglist: str,
+    *,
     multi_line_parameter_list: bool = False,
     trailing_comma: bool = True,
+    env: BuildEnvironment,
 ) -> None:
     """'Parse' a list of arguments separated by commas.
 
     Arguments can have "optional" annotations given by enclosing them in
     brackets.  Currently, this will split at any comma, even if it's inside a
     string literal (e.g. default argument value).
     """
+    # TODO: decompose 'env' parameter into only the required bits
     paramlist = addnodes.desc_parameterlist()
     paramlist['multi_line_parameter_list'] = multi_line_parameter_list
     paramlist['multi_line_trailing_comma'] = trailing_comma
@@ -583,9 +586,30 @@ def _pseudo_parse_arglist(
                 ends_open += 1
                 argument = argument[:-1].strip()
             if argument:
-                stack[-1] += addnodes.desc_parameter(
-                    '', '', addnodes.desc_sig_name(argument, argument)
-                )
+                param_with_annotation, _, default_value = argument.partition('=')
+                param_name, _, annotation = param_with_annotation.partition(':')
+                del param_with_annotation
+
+                node = addnodes.desc_parameter()
+                node += addnodes.desc_sig_name('', param_name.strip())
+                if annotation:
+                    children = _parse_annotation(annotation.strip(), env=env)
+                    node += addnodes.desc_sig_punctuation('', ':')
+                    node += addnodes.desc_sig_space()
+                    node += addnodes.desc_sig_name('', '', *children)  # type: ignore[arg-type]
+                if default_value:
+                    if annotation:
+                        node += addnodes.desc_sig_space()
+                    node += addnodes.desc_sig_operator('', '=')
+                    if annotation:
+                        node += addnodes.desc_sig_space()
+                    node += nodes.inline(
+                        '',
+                        default_value.strip(),
+                        classes=['default_value'],
+                        support_smartquotes=False,
+                    )
+                stack[-1] += node
             while ends_open:
                 stack.append(addnodes.desc_optional())
                 stack[-2] += stack[-1]

sphinx/domains/python/_object.py

@@ -363,8 +363,9 @@ def handle_signature(self, sig: str, signode: desc_signature) -> tuple[str, str]
                 _pseudo_parse_arglist(
                     signode,
                     arglist,
-                    multi_line_parameter_list,
-                    trailing_comma,
+                    multi_line_parameter_list=multi_line_parameter_list,
+                    trailing_comma=trailing_comma,
+                    env=self.env,
                 )
             except (NotImplementedError, ValueError) as exc:
                 # duplicated parameter names raise ValueError and not a SyntaxError
@@ -374,8 +375,9 @@ def handle_signature(self, sig: str, signode: desc_signature) -> tuple[str, str]
                 _pseudo_parse_arglist(
                     signode,
                     arglist,
-                    multi_line_parameter_list,
-                    trailing_comma,
+                    multi_line_parameter_list=multi_line_parameter_list,
+                    trailing_comma=trailing_comma,
+                    env=self.env,
                 )
         else:
             if self.needs_arglist():

tests/test_domains/test_domain_py.py

@@ -38,20 +38,25 @@
 from sphinx.testing.util import assert_node
 from sphinx.writers.text import STDINDENT
 
+TYPE_CHECKING = False
+if TYPE_CHECKING:
+    from sphinx.application import Sphinx
+    from sphinx.environment import BuildEnvironment
 
-def parse(sig):
+
+def parse(sig: str, *, env: BuildEnvironment) -> str:
     m = py_sig_re.match(sig)
     if m is None:
         raise ValueError
     _name_prefix, _tp_list, _name, arglist, _retann = m.groups()
     signode = addnodes.desc_signature(sig, '')
-    _pseudo_parse_arglist(signode, arglist)
+    _pseudo_parse_arglist(signode, arglist, env=env)
     return signode.astext()
 
 
-def test_function_signatures() -> None:
-    rv = parse("compile(source : string, filename, symbol='file')")
-    assert rv == "(source : string, filename, symbol='file')"
+def test_function_signatures(app: Sphinx) -> None:
+    rv = parse("compile(source : string, filename, symbol='file')", env=app.env)
+    assert rv == "(source: string, filename, symbol='file')"
 
     for params, expect in [
         ('(a=1)', '(a=1)'),
@@ -60,17 +65,17 @@ def test_function_signatures() -> None:
         ('(a=1[, b=None])', '(a=1, [b=None])'),
         ('(a=[], [b=None])', '(a=[], [b=None])'),
         ('(a=[][, b=None])', '(a=[], [b=None])'),
-        ('(a: Foo[Bar]=[][, b=None])', '(a: Foo[Bar]=[], [b=None])'),
+        ('(a: Foo[Bar]=[][, b=None])', '(a: Foo[Bar] = [], [b=None])'),
     ]:
-        rv = parse(f'func{params}')
+        rv = parse(f'func{params}', env=app.env)
         assert rv == expect
 
         # Note: 'def f[Foo[Bar]]()' is not valid Python but people might write
         # it in a reST document to convene the intent of a higher-kinded type
         # variable.
         for tparams in ['', '[Foo]', '[Foo[Bar]]']:
             for retann in ['', '-> Foo', '-> Foo[Bar]', '-> anything else']:
-                rv = parse(f'func{tparams}{params} {retann}'.rstrip())
+                rv = parse(f'func{tparams}{params} {retann}'.rstrip(), env=app.env)
                 assert rv == expect
 
 

tests/test_domains/test_domain_py_pyfunction.py

@@ -27,6 +27,10 @@
 from sphinx.testing import restructuredtext
 from sphinx.testing.util import assert_node
 
+TYPE_CHECKING = False
+if TYPE_CHECKING:
+    from sphinx.application import Sphinx
+
 
 @pytest.mark.sphinx('html', testroot='_blank')
 def test_pyfunction(app):
@@ -487,6 +491,58 @@ def test_optional_pyfunction_signature(app):
     )
 
 
+@pytest.mark.sphinx('html', testroot='_blank')
+def test_pyfunction_signature_with_bracket(app: Sphinx) -> None:
+    text = '.. py:function:: hello(a : ~typing.Any = <b>) -> None'
+    doctree = restructuredtext.parse(app, text)
+    assert_node(
+        doctree,
+        (
+            addnodes.index,
+            [
+                desc,
+                (
+                    [
+                        desc_signature,
+                        (
+                            [desc_name, 'hello'],
+                            desc_parameterlist,
+                            [desc_returns, pending_xref, 'None'],
+                        ),
+                    ],
+                    desc_content,
+                ),
+            ],
+        ),
+    )
+    assert_node(
+        doctree[1],
+        addnodes.desc,
+        desctype='function',
+        domain='py',
+        objtype='function',
+        no_index=False,
+    )
+    assert_node(
+        doctree[1][0][1],  # type: ignore[index]
+        (
+            [
+                desc_parameter,
+                (
+                    [desc_sig_name, 'a'],
+                    [desc_sig_punctuation, ':'],
+                    desc_sig_space,
+                    [desc_sig_name, pending_xref, 'Any'],
+                    desc_sig_space,
+                    [desc_sig_operator, '='],
+                    desc_sig_space,
+                    [nodes.inline, '<b>'],
+                ),
+            ],
+        ),
+    )
+
+
 @pytest.mark.sphinx(
     'html',
     testroot='root',