Skip to content

Commit

Permalink
Merge pull request #8095 from keewis/toggle-preprocessor
Browse files Browse the repository at this point in the history 
add a setting to enable / disable the numpy type preprocessor
  • Loading branch information
@tk0miya
tk0miya committed Aug 13, 2020
2 parents e70a30e + 1c38824 commit 6e62d33
Show file tree
Hide file tree
Showing 3 changed files with 64 additions and 35 deletions.
7 changes: 6 additions & 1 deletion sphinx/ext/napoleon/__init__.py
View file
Expand Up @@ -41,6 +41,7 @@ class Config:
napoleon_use_param = True
napoleon_use_rtype = True
napoleon_use_keyword = True
napoleon_preprocess_types = False
napoleon_type_aliases = None
napoleon_custom_sections = None
Expand Down Expand Up @@ -237,9 +238,12 @@ def __unicode__(self):
:returns: *bool* -- True if successful, False otherwise
napoleon_preprocess_types : :obj:`bool` (Defaults to False)
Enable the type preprocessor for numpy style docstrings.
napoleon_type_aliases : :obj:`dict` (Defaults to None)
Add a mapping of strings to string, translating types in numpy
style docstrings.
style docstrings. Only works if ``napoleon_preprocess_types = True``.
napoleon_custom_sections : :obj:`list` (Defaults to None)
Add a list of custom sections to include, expanding the list of parsed sections.
Expand Down Expand Up @@ -268,6 +272,7 @@ def __unicode__(self):
'napoleon_use_param': (True, 'env'),
'napoleon_use_rtype': (True, 'env'),
'napoleon_use_keyword': (True, 'env'),
'napoleon_preprocess_types': (False, 'env'),
'napoleon_type_aliases': (None, 'env'),
'napoleon_custom_sections': (None, 'env')
}
Expand Down
11 changes: 6 additions & 5 deletions sphinx/ext/napoleon/docstring.py
View file
Expand Up @@ -1104,11 +1104,12 @@ def _consume_field(self, parse_type: bool = True, prefer_type: bool = False
_name, _type = line, ''
_name, _type = _name.strip(), _type.strip()
_name = self._escape_args_and_kwargs(_name)
_type = _convert_numpy_type_spec(
_type,
location=self._get_location(),
translations=self._config.napoleon_type_aliases or {},
)
if self._config.napoleon_preprocess_types:
_type = _convert_numpy_type_spec(
_type,
location=self._get_location(),
translations=self._config.napoleon_type_aliases or {},
)

if prefer_type and not _type:
_type, _name = _name, _type
Expand Down
81 changes: 52 additions & 29 deletions tests/test_ext_napoleon_docstring.py
View file
Expand Up @@ -66,19 +66,19 @@ def test_attributes_docstring(self):
Quick description of attr1
:type: :class:`Arbitrary type`
:type: Arbitrary type
.. attribute:: attr2
Quick description of attr2
:type: :class:`Another arbitrary type`
:type: Another arbitrary type
.. attribute:: attr3
Adds a newline after the type
:type: :class:`Type`
:type: Type
"""

self.assertEqual(expected, actual)
Expand Down Expand Up @@ -1311,12 +1311,34 @@ def test_docstrings(self):
config = Config(
napoleon_use_param=False,
napoleon_use_rtype=False,
napoleon_use_keyword=False)
napoleon_use_keyword=False,
napoleon_preprocess_types=True)
for docstring, expected in self.docstrings:
actual = str(NumpyDocstring(dedent(docstring), config))
expected = dedent(expected)
self.assertEqual(expected, actual)

def test_type_preprocessor(self):
docstring = dedent("""
Single line summary
Parameters
----------
arg1:str
Extended
description of arg1
""")

config = Config(napoleon_preprocess_types=False, napoleon_use_param=False)
actual = str(NumpyDocstring(docstring, config))
expected = dedent("""
Single line summary
:Parameters: **arg1** (*str*) -- Extended
description of arg1
""")
self.assertEqual(expected, actual)

def test_parameters_with_class_reference(self):
docstring = """\
Parameters
Expand Down Expand Up @@ -1352,17 +1374,17 @@ def test_multiple_parameters(self):
config = Config(napoleon_use_param=False)
actual = str(NumpyDocstring(docstring, config))
expected = """\
:Parameters: **x1, x2** (:class:`array_like`) -- Input arrays, description of ``x1``, ``x2``.
:Parameters: **x1, x2** (*array_like*) -- Input arrays, description of ``x1``, ``x2``.
"""
self.assertEqual(expected, actual)

config = Config(napoleon_use_param=True)
actual = str(NumpyDocstring(dedent(docstring), config))
expected = """\
:param x1: Input arrays, description of ``x1``, ``x2``.
:type x1: :class:`array_like`
:type x1: array_like
:param x2: Input arrays, description of ``x1``, ``x2``.
:type x2: :class:`array_like`
:type x2: array_like
"""
self.assertEqual(expected, actual)

Expand All @@ -1377,15 +1399,15 @@ def test_parameters_without_class_reference(self):
config = Config(napoleon_use_param=False)
actual = str(NumpyDocstring(docstring, config))
expected = """\
:Parameters: **param1** (:class:`MyClass instance`)
:Parameters: **param1** (*MyClass instance*)
"""
self.assertEqual(expected, actual)

config = Config(napoleon_use_param=True)
actual = str(NumpyDocstring(dedent(docstring), config))
expected = """\
:param param1:
:type param1: :class:`MyClass instance`
:type param1: MyClass instance
"""
self.assertEqual(expected, actual)

Expand Down Expand Up @@ -1474,7 +1496,7 @@ def test_underscore_in_attribute(self):

expected = """
:ivar arg_: some description
:vartype arg_: :class:`type`
:vartype arg_: type
"""

config = Config(napoleon_use_ivar=True)
Expand All @@ -1494,7 +1516,7 @@ def test_underscore_in_attribute_strip_signature_backslash(self):

expected = """
:ivar arg\\_: some description
:vartype arg\\_: :class:`type`
:vartype arg\\_: type
"""

config = Config(napoleon_use_ivar=True)
Expand Down Expand Up @@ -1862,74 +1884,74 @@ def test_list_in_parameter_description(self):
expected = """One line summary.
:param no_list:
:type no_list: :class:`int`
:type no_list: int
:param one_bullet_empty:
*
:type one_bullet_empty: :class:`int`
:type one_bullet_empty: int
:param one_bullet_single_line:
- first line
:type one_bullet_single_line: :class:`int`
:type one_bullet_single_line: int
:param one_bullet_two_lines:
+ first line
continued
:type one_bullet_two_lines: :class:`int`
:type one_bullet_two_lines: int
:param two_bullets_single_line:
- first line
- second line
:type two_bullets_single_line: :class:`int`
:type two_bullets_single_line: int
:param two_bullets_two_lines:
* first line
continued
* second line
continued
:type two_bullets_two_lines: :class:`int`
:type two_bullets_two_lines: int
:param one_enumeration_single_line:
1. first line
:type one_enumeration_single_line: :class:`int`
:type one_enumeration_single_line: int
:param one_enumeration_two_lines:
1) first line
continued
:type one_enumeration_two_lines: :class:`int`
:type one_enumeration_two_lines: int
:param two_enumerations_one_line:
(iii) first line
(iv) second line
:type two_enumerations_one_line: :class:`int`
:type two_enumerations_one_line: int
:param two_enumerations_two_lines:
a. first line
continued
b. second line
continued
:type two_enumerations_two_lines: :class:`int`
:type two_enumerations_two_lines: int
:param one_definition_one_line:
item 1
first line
:type one_definition_one_line: :class:`int`
:type one_definition_one_line: int
:param one_definition_two_lines:
item 1
first line
continued
:type one_definition_two_lines: :class:`int`
:type one_definition_two_lines: int
:param two_definitions_one_line:
item 1
first line
item 2
second line
:type two_definitions_one_line: :class:`int`
:type two_definitions_one_line: int
:param two_definitions_two_lines:
item 1
first line
continued
item 2
second line
continued
:type two_definitions_two_lines: :class:`int`
:type two_definitions_two_lines: int
:param one_definition_blank_line:
item 1
first line
extra first line
:type one_definition_blank_line: :class:`int`
:type one_definition_blank_line: int
:param two_definitions_blank_lines:
item 1
Expand All @@ -1942,12 +1964,12 @@ def test_list_in_parameter_description(self):
second line
extra second line
:type two_definitions_blank_lines: :class:`int`
:type two_definitions_blank_lines: int
:param definition_after_normal_text: text line
item 1
first line
:type definition_after_normal_text: :class:`int`
:type definition_after_normal_text: int
"""
config = Config(napoleon_use_param=True)
actual = str(NumpyDocstring(docstring, config))
Expand Down Expand Up @@ -2041,7 +2063,7 @@ def test_list_in_parameter_description(self):
item 1
first line
"""
config = Config(napoleon_use_param=False)
config = Config(napoleon_use_param=False, napoleon_preprocess_types=True)
actual = str(NumpyDocstring(docstring, config))
self.assertEqual(expected, actual)

Expand Down Expand Up @@ -2222,6 +2244,7 @@ def test_parameter_types(self):
config = Config(
napoleon_use_param=True,
napoleon_use_rtype=True,
napoleon_preprocess_types=True,
napoleon_type_aliases=translations,
)
actual = str(NumpyDocstring(docstring, config))
Expand Down

0 comments on commit 6e62d33

Please sign in to comment.