Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

add a setting to enable / disable the numpy type preprocessor #8095

Merged
merged 4 commits into from Aug 13, 2020
Merged

add a setting to enable / disable the numpy type preprocessor #8095

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
2d180e4
add a setting to disable the type preprocessor
keewis Aug 10, 2020
27c252c
only preprocess if the preprocessor is enabled
keewis Aug 10, 2020
be65bde
fix a typo
keewis Aug 10, 2020
1c38824
default to False and update the tests
keewis Aug 12, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
7 changes: 6 additions & 1 deletion sphinx/ext/napoleon/__init__.py
View file
Open in desktop
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
Open in desktop
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
Open in desktop
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