Skip to content

Commit

Permalink
Merge pull request #8552 from tk0miya/8236_napoleon_receives_section
Browse files Browse the repository at this point in the history
Close #8236: napoleon: Support numpydoc's "Receives" section
  • Loading branch information
tk0miya authored Dec 20, 2020
2 parents 7f1284f + f50b999 commit 6e8ea85
Show file tree
Hide file tree
Showing 3 changed files with 82 additions and 0 deletions.
1 change: 1 addition & 0 deletions CHANGES
Original file line number Diff line number Diff line change
Expand Up @@ -44,6 +44,7 @@ Features added
* #8460: autodoc: Support custom types defined by typing.NewType
* #8285: napoleon: Add :confval:`napoleon_attr_annotations` to merge type hints
on source code automatically if any type is specified in docstring
* #8236: napoleon: Support numpydoc's "Receives" section
* #6914: Add a new event :event:`warn-missing-reference` to custom warning
messages when failed to resolve a cross-reference
* #6914: Emit a detailed warning when failed to resolve a ``:ref:`` reference
Expand Down
11 changes: 11 additions & 0 deletions sphinx/ext/napoleon/docstring.py
Original file line number Diff line number Diff line change
Expand Up @@ -179,6 +179,8 @@ def __init__(self, docstring: Union[str, List[str]], config: SphinxConfig = None
'notes': self._parse_notes_section,
'other parameters': self._parse_other_parameters_section,
'parameters': self._parse_parameters_section,
'receive': self._parse_receives_section,
'receives': self._parse_receives_section,
'return': self._parse_returns_section,
'returns': self._parse_returns_section,
'raise': self._parse_raises_section,
Expand Down Expand Up @@ -714,6 +716,15 @@ def _parse_raises_section(self, section: str) -> List[str]:
lines.append('')
return lines

def _parse_receives_section(self, section: str) -> List[str]:
if self._config.napoleon_use_param:
# Allow to declare multiple parameters at once (ex: x, y: int)
fields = self._consume_fields(multiple=True)
return self._format_docutils_params(fields)
else:
fields = self._consume_fields()
return self._format_fields(_('Receives'), fields)

def _parse_references_section(self, section: str) -> List[str]:
use_admonition = self._config.napoleon_use_admonition_for_references
return self._parse_generic_section(_('References'), use_admonition)
Expand Down
70 changes: 70 additions & 0 deletions tests/test_ext_napoleon_docstring.py
Original file line number Diff line number Diff line change
Expand Up @@ -303,6 +303,34 @@ class GoogleDocstringTest(BaseDocstringTest):
"""
Single line summary
Receive:
arg1 (list(int)): Description
arg2 (list[int]): Description
""",
"""
Single line summary
:Receives: * **arg1** (*list(int)*) -- Description
* **arg2** (*list[int]*) -- Description
"""
), (
"""
Single line summary
Receives:
arg1 (list(int)): Description
arg2 (list[int]): Description
""",
"""
Single line summary
:Receives: * **arg1** (*list(int)*) -- Description
* **arg2** (*list[int]*) -- Description
"""
), (
"""
Single line summary
Yield:
str:Extended
description of yielded value
Expand Down Expand Up @@ -1263,6 +1291,48 @@ class NumpyDocstringTest(BaseDocstringTest):
"""
Single line summary
Receive
-------
arg1:str
Extended
description of arg1
arg2 : int
Extended
description of arg2
""",
"""
Single line summary
:Receives: * **arg1** (:class:`str`) -- Extended
description of arg1
* **arg2** (:class:`int`) -- Extended
description of arg2
"""
), (
"""
Single line summary
Receives
--------
arg1:str
Extended
description of arg1
arg2 : int
Extended
description of arg2
""",
"""
Single line summary
:Receives: * **arg1** (:class:`str`) -- Extended
description of arg1
* **arg2** (:class:`int`) -- Extended
description of arg2
"""
), (
"""
Single line summary
Yield
-----
str
Expand Down

0 comments on commit 6e8ea85

Please sign in to comment.