Skip to content

Commit

Permalink
py domain: Allow to make a style for arguments of functions and metho…
Browse files Browse the repository at this point in the history 
…ds (refs: sphinx-doc#6417)
  • Loading branch information
@tk0miya
tk0miya committed Feb 29, 2020
1 parent 675e7e5 commit c3cc0d5
Show file tree
Hide file tree
Showing 4 changed files with 71 additions and 40 deletions.
3 changes: 3 additions & 0 deletions CHANGES
View file
Expand Up @@ -19,6 +19,8 @@ Incompatible changes
when ``:inherited-members:`` and ``:special-members:`` are given.
* #6830: py domain: ``meta`` fields in info-field-list becomes reserved. They
are not displayed on output document now
* #6417: py domain: doctree of desc_parameterlist has been changed. The
argument names, annotations and default values are wrapped with inline node
* The structure of ``sphinx.events.EventManager.listeners`` has changed
* Due to the scoping changes for :rst:dir:`productionlist` some uses of
:rst:role:`token` must be modified to include the scope which was previously
Expand Down Expand Up @@ -49,6 +51,7 @@ Features added
* #6558: std domain: emit a warning for duplicated generic objects
* #6830: py domain: Add new event: :event:`object-description-transform`
* py domain: Support lambda functions in function signature
* #6417: py domain: Allow to make a style for arguments of functions and methods
* Support priority of event handlers. For more detail, see
:py:meth:`.Sphinx.connect()`
* #3077: Implement the scoping for :rst:dir:`productionlist` as indicated
Expand Down
25 changes: 16 additions & 9 deletions sphinx/domains/python.py
View file
Expand Up @@ -72,35 +72,42 @@ def _parse_arglist(arglist: str) -> addnodes.desc_parameterlist:
for param in sig.parameters.values():
if param.kind != param.POSITIONAL_ONLY and last_kind == param.POSITIONAL_ONLY:
# PEP-570: Separator for Positional Only Parameter: /
params += addnodes.desc_parameter('', nodes.Text('/'))
params += addnodes.desc_parameter('', '', addnodes.desc_sig_operator('', '/'))
if param.kind == param.KEYWORD_ONLY and last_kind in (param.POSITIONAL_OR_KEYWORD,
param.POSITIONAL_ONLY,
None):
# PEP-3102: Separator for Keyword Only Parameter: *
params += addnodes.desc_parameter('', nodes.Text('*'))
params += addnodes.desc_parameter('', '', addnodes.desc_sig_operator('', '*'))

node = addnodes.desc_parameter()
if param.kind == param.VAR_POSITIONAL:
node += nodes.Text('*' + param.name)
node += addnodes.desc_sig_operator('', '*')
node += addnodes.desc_sig_name('', param.name)
elif param.kind == param.VAR_KEYWORD:
node += nodes.Text('**' + param.name)
node += addnodes.desc_sig_operator('', '**')
node += addnodes.desc_sig_name('', param.name)
else:
node += nodes.Text(param.name)
node += addnodes.desc_sig_name('', param.name)

if param.annotation is not param.empty:
node += nodes.Text(': ' + param.annotation)
node += addnodes.desc_sig_punctuation('', ':')
node += nodes.Text(' ')
node += addnodes.desc_sig_name('', param.annotation)
if param.default is not param.empty:
if param.annotation is not param.empty:
node += nodes.Text(' = ' + str(param.default))
node += nodes.Text(' ')
node += addnodes.desc_sig_operator('', '=')
node += nodes.Text(' ')
else:
node += nodes.Text('=' + str(param.default))
node += addnodes.desc_sig_operator('', '=')
node += nodes.inline('', param.default, classes=['default_value'])

params += node
last_kind = param.kind

if last_kind == Parameter.POSITIONAL_ONLY:
# PEP-570: Separator for Positional Only Parameter: /
params += addnodes.desc_parameter('', nodes.Text('/'))
params += addnodes.desc_parameter('', '', addnodes.desc_sig_operator('', '/'))

return params

Expand Down
3 changes: 2 additions & 1 deletion tests/test_build_html.py
View file
Expand Up @@ -177,7 +177,8 @@ def test_html4_output(app, status, warning):
],
'autodoc.html': [
(".//dl[@class='py class']/dt[@id='autodoc_target.Class']", ''),
(".//dl[@class='py function']/dt[@id='autodoc_target.function']/em", r'\*\*kwds'),
(".//dl[@class='py function']/dt[@id='autodoc_target.function']/em/span", r'\*\*'),
(".//dl[@class='py function']/dt[@id='autodoc_target.function']/em/span", r'kwds'),
(".//dd/p", r'Return spam\.'),
],
'extapi.html': [
Expand Down
80 changes: 50 additions & 30 deletions tests/test_domain_py.py
View file
Expand Up @@ -17,7 +17,8 @@
from sphinx import addnodes
from sphinx.addnodes import (
desc, desc_addname, desc_annotation, desc_content, desc_name, desc_optional,
desc_parameter, desc_parameterlist, desc_returns, desc_signature
desc_parameter, desc_parameterlist, desc_returns, desc_signature,
desc_sig_name, desc_sig_operator, desc_sig_punctuation,
)
from sphinx.domains import IndexEntry
from sphinx.domains.python import (
Expand Down Expand Up @@ -243,8 +244,10 @@ def test_pyfunction_signature(app):
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")])
[desc_parameterlist, desc_parameter, ([desc_sig_name, "name"],
[desc_sig_punctuation, ":"],
" ",
[nodes.inline, "str"])])


def test_pyfunction_signature_full(app):
Expand All @@ -259,17 +262,31 @@ def test_pyfunction_signature_full(app):
assert_node(doctree[1], addnodes.desc, desctype="function",
domain="py", objtype="function", noindex=False)
assert_node(doctree[1][0][1],
[desc_parameterlist, ([desc_parameter, ("a",
": str")],
[desc_parameter, ("b",
"=1")],
[desc_parameter, ("*args",
": str")],
[desc_parameter, ("c",
": bool",
" = True")],
[desc_parameter, ("**kwargs",
": str")])])
[desc_parameterlist, ([desc_parameter, ([desc_sig_name, "a"],
[desc_sig_punctuation, ":"],
" ",
[desc_sig_name, "str"])],
[desc_parameter, ([desc_sig_name, "b"],
[desc_sig_operator, "="],
[nodes.inline, "1"])],
[desc_parameter, ([desc_sig_operator, "*"],
[desc_sig_name, "args"],
[desc_sig_punctuation, ":"],
" ",
[desc_sig_name, "str"])],
[desc_parameter, ([desc_sig_name, "c"],
[desc_sig_punctuation, ":"],
" ",
[desc_sig_name, "bool"],
" ",
[desc_sig_operator, "="],
" ",
[nodes.inline, "True"])],
[desc_parameter, ([desc_sig_operator, "**"],
[desc_sig_name, "kwargs"],
[desc_sig_punctuation, ":"],
" ",
[desc_sig_name, "str"])])])


@pytest.mark.skipif(sys.version_info < (3, 8), reason='python 3.8+ is required.')
Expand All @@ -278,37 +295,40 @@ def test_pyfunction_signature_full_py38(app):
text = ".. py:function:: hello(*, a)"
doctree = restructuredtext.parse(app, text)
assert_node(doctree[1][0][1],
[desc_parameterlist, ([desc_parameter, "*"],
[desc_parameter, ("a",
"=None")])])
[desc_parameterlist, ([desc_parameter, nodes.inline, "*"],
[desc_parameter, ([desc_sig_name, "a"],
[desc_sig_operator, "="],
[nodes.inline, "None"])])])

# case: separator in the middle
text = ".. py:function:: hello(a, /, b, *, c)"
doctree = restructuredtext.parse(app, text)
assert_node(doctree[1][0][1],
[desc_parameterlist, ([desc_parameter, "a"],
[desc_parameter, "/"],
[desc_parameter, "b"],
[desc_parameter, "*"],
[desc_parameter, ("c",
"=None")])])
[desc_parameterlist, ([desc_parameter, desc_sig_name, "a"],
[desc_parameter, desc_sig_operator, "/"],
[desc_parameter, desc_sig_name, "b"],
[desc_parameter, desc_sig_operator, "*"],
[desc_parameter, ([desc_sig_name, "c"],
[desc_sig_operator, "="],
[nodes.inline, "None"])])])

# case: separator in the middle (2)
text = ".. py:function:: hello(a, /, *, b)"
doctree = restructuredtext.parse(app, text)
assert_node(doctree[1][0][1],
[desc_parameterlist, ([desc_parameter, "a"],
[desc_parameter, "/"],
[desc_parameter, "*"],
[desc_parameter, ("b",
"=None")])])
[desc_parameterlist, ([desc_parameter, desc_sig_name, "a"],
[desc_parameter, desc_sig_operator, "/"],
[desc_parameter, desc_sig_operator, "*"],
[desc_parameter, ([desc_sig_name, "b"],
[desc_sig_operator, "="],
[nodes.inline, "None"])])])

# case: separator at tail
text = ".. py:function:: hello(a, /)"
doctree = restructuredtext.parse(app, text)
assert_node(doctree[1][0][1],
[desc_parameterlist, ([desc_parameter, "a"],
[desc_parameter, "/"])])
[desc_parameterlist, ([desc_parameter, desc_sig_name, "a"],
[desc_parameter, desc_sig_operator, "/"])])


def test_optional_pyfunction_signature(app):
Expand Down

0 comments on commit c3cc0d5

Please sign in to comment.