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

enable type preprocessing without use_param #8049

Merged
merged 2 commits into from Aug 7, 2020
Merged

enable type preprocessing without use_param #8049

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
cac6d17
preprocess even with napoleon_use_param = False
keewis Aug 4, 2020
cb61f0f
document that we don't require use_param = True anymore
keewis Aug 4, 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
2 changes: 1 addition & 1 deletion sphinx/ext/napoleon/__init__.py
View file
Open in desktop
Expand Up @@ -239,7 +239,7 @@ def __unicode__(self):

napoleon_type_aliases : :obj:`dict` (Defaults to None)
Add a mapping of strings to string, translating types in numpy
style docstrings. Only works when ``napoleon_use_param = True``.
style docstrings.

napoleon_custom_sections : :obj:`list` (Defaults to None)
Add a list of custom sections to include, expanding the list of parsed sections.
Expand Down
20 changes: 6 additions & 14 deletions sphinx/ext/napoleon/docstring.py
View file
Open in desktop
Expand Up @@ -930,16 +930,9 @@ def convert_obj(obj, translations, default_translation):
for token in combined_tokens
]

# don't use the object role if it's not necessary
default_translation = (
":class:`%s`"
if not all(type_ == "obj" for _, type_ in types)
else "%s"
)

converters = {
"literal": lambda x: "``%s``" % x,
"obj": lambda x: convert_obj(x, translations, default_translation),
"obj": lambda x: convert_obj(x, translations, ":class:`%s`"),
"control": lambda x: "*%s*" % x,
"delimiter": lambda x: x,
"reference": lambda x: x,
Expand Down Expand Up @@ -1067,12 +1060,11 @@ 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)
if self._config.napoleon_use_param:
_type = _convert_numpy_type_spec(
_type,
location=self._get_location(),
translations=self._config.napoleon_type_aliases or {},
)
_type = _convert_numpy_type_spec(
_type,
location=self._get_location(),
translations=self._config.napoleon_type_aliases or {},
)
keewis marked this conversation as resolved.
Show resolved Hide resolved

if prefer_type and not _type:
_type, _name = _name, _type
Expand Down
96 changes: 48 additions & 48 deletions tests/test_ext_napoleon_docstring.py
View file
Open in desktop
Expand Up @@ -64,19 +64,19 @@ def test_attributes_docstring(self):

Quick description of attr1

:type: Arbitrary type
:type: :class:`Arbitrary type`

.. attribute:: attr2

Quick description of attr2

:type: Another arbitrary type
:type: :class:`Another arbitrary type`

.. attribute:: attr3

Adds a newline after the type

:type: Type
:type: :class:`Type`
"""

self.assertEqual(expected, actual)
Expand Down Expand Up @@ -1108,7 +1108,7 @@ class NumpyDocstringTest(BaseDocstringTest):
"""
Single line summary

:Parameters: **arg1** (*str*) -- Extended
:Parameters: **arg1** (:class:`str`) -- Extended
description of arg1
"""
), (
Expand Down Expand Up @@ -1136,14 +1136,14 @@ class NumpyDocstringTest(BaseDocstringTest):
"""
Single line summary

:Parameters: * **arg1** (*str*) -- Extended
:Parameters: * **arg1** (:class:`str`) -- Extended
description of arg1
* **arg2** (*int*) -- Extended
* **arg2** (:class:`int`) -- Extended
description of arg2

:Keyword Arguments: * **kwarg1** (*str*) -- Extended
:Keyword Arguments: * **kwarg1** (:class:`str`) -- Extended
description of kwarg1
* **kwarg2** (*int*) -- Extended
* **kwarg2** (:class:`int`) -- Extended
description of kwarg2
"""
), (
Expand Down Expand Up @@ -1194,7 +1194,7 @@ class NumpyDocstringTest(BaseDocstringTest):
"""
Single line summary

:Parameters: * **arg1** (*str*) -- Extended description of arg1
:Parameters: * **arg1** (:class:`str`) -- Extended description of arg1
* **\\*args** -- Variable length argument list.
* **\\*\\*kwargs** -- Arbitrary keyword arguments.
"""
Expand Down Expand Up @@ -1316,15 +1316,15 @@ def test_parameters_without_class_reference(self):
config = Config(napoleon_use_param=False)
actual = str(NumpyDocstring(docstring, config))
expected = """\
:Parameters: **param1** (*MyClass instance*)
:Parameters: **param1** (:class:`MyClass instance`)
"""
self.assertEqual(expected, actual)

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

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

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

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

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

config = Config(napoleon_use_ivar=True)
Expand Down Expand Up @@ -1801,74 +1801,74 @@ def test_list_in_parameter_description(self):
expected = """One line summary.

:param no_list:
:type no_list: int
:type no_list: :class:`int`
:param one_bullet_empty:
*
:type one_bullet_empty: int
:type one_bullet_empty: :class:`int`
:param one_bullet_single_line:
- first line
:type one_bullet_single_line: int
:type one_bullet_single_line: :class:`int`
:param one_bullet_two_lines:
+ first line
continued
:type one_bullet_two_lines: int
:type one_bullet_two_lines: :class:`int`
:param two_bullets_single_line:
- first line
- second line
:type two_bullets_single_line: int
:type two_bullets_single_line: :class:`int`
:param two_bullets_two_lines:
* first line
continued
* second line
continued
:type two_bullets_two_lines: int
:type two_bullets_two_lines: :class:`int`
:param one_enumeration_single_line:
1. first line
:type one_enumeration_single_line: int
:type one_enumeration_single_line: :class:`int`
:param one_enumeration_two_lines:
1) first line
continued
:type one_enumeration_two_lines: int
:type one_enumeration_two_lines: :class:`int`
:param two_enumerations_one_line:
(iii) first line
(iv) second line
:type two_enumerations_one_line: int
:type two_enumerations_one_line: :class:`int`
:param two_enumerations_two_lines:
a. first line
continued
b. second line
continued
:type two_enumerations_two_lines: int
:type two_enumerations_two_lines: :class:`int`
:param one_definition_one_line:
item 1
first line
:type one_definition_one_line: int
:type one_definition_one_line: :class:`int`
:param one_definition_two_lines:
item 1
first line
continued
:type one_definition_two_lines: int
:type one_definition_two_lines: :class:`int`
:param two_definitions_one_line:
item 1
first line
item 2
second line
:type two_definitions_one_line: int
:type two_definitions_one_line: :class:`int`
:param two_definitions_two_lines:
item 1
first line
continued
item 2
second line
continued
:type two_definitions_two_lines: int
:type two_definitions_two_lines: :class:`int`
:param one_definition_blank_line:
item 1

first line

extra first line
:type one_definition_blank_line: int
:type one_definition_blank_line: :class:`int`
:param two_definitions_blank_lines:
item 1

Expand All @@ -1881,88 +1881,88 @@ def test_list_in_parameter_description(self):
second line

extra second line
:type two_definitions_blank_lines: int
:type two_definitions_blank_lines: :class:`int`
:param definition_after_normal_text: text line

item 1
first line
:type definition_after_normal_text: int
:type definition_after_normal_text: :class:`int`
"""
config = Config(napoleon_use_param=True)
actual = str(NumpyDocstring(docstring, config))
self.assertEqual(expected, actual)

expected = """One line summary.

:Parameters: * **no_list** (*int*)
* **one_bullet_empty** (*int*) --
:Parameters: * **no_list** (:class:`int`)
* **one_bullet_empty** (:class:`int`) --

*
* **one_bullet_single_line** (*int*) --
* **one_bullet_single_line** (:class:`int`) --

- first line
* **one_bullet_two_lines** (*int*) --
* **one_bullet_two_lines** (:class:`int`) --

+ first line
continued
* **two_bullets_single_line** (*int*) --
* **two_bullets_single_line** (:class:`int`) --

- first line
- second line
* **two_bullets_two_lines** (*int*) --
* **two_bullets_two_lines** (:class:`int`) --

* first line
continued
* second line
continued
* **one_enumeration_single_line** (*int*) --
* **one_enumeration_single_line** (:class:`int`) --

1. first line
* **one_enumeration_two_lines** (*int*) --
* **one_enumeration_two_lines** (:class:`int`) --

1) first line
continued
* **two_enumerations_one_line** (*int*) --
* **two_enumerations_one_line** (:class:`int`) --

(iii) first line
(iv) second line
* **two_enumerations_two_lines** (*int*) --
* **two_enumerations_two_lines** (:class:`int`) --

a. first line
continued
b. second line
continued
* **one_definition_one_line** (*int*) --
* **one_definition_one_line** (:class:`int`) --

item 1
first line
* **one_definition_two_lines** (*int*) --
* **one_definition_two_lines** (:class:`int`) --

item 1
first line
continued
* **two_definitions_one_line** (*int*) --
* **two_definitions_one_line** (:class:`int`) --

item 1
first line
item 2
second line
* **two_definitions_two_lines** (*int*) --
* **two_definitions_two_lines** (:class:`int`) --

item 1
first line
continued
item 2
second line
continued
* **one_definition_blank_line** (*int*) --
* **one_definition_blank_line** (:class:`int`) --

item 1

first line

extra first line
* **two_definitions_blank_lines** (*int*) --
* **two_definitions_blank_lines** (:class:`int`) --

item 1

Expand All @@ -1975,7 +1975,7 @@ def test_list_in_parameter_description(self):
second line

extra second line
* **definition_after_normal_text** (*int*) -- text line
* **definition_after_normal_text** (:class:`int`) -- text line

item 1
first line
Expand Down Expand Up @@ -2111,7 +2111,7 @@ def test_parameter_types(self):
""")
expected = dedent("""\
:param param1: the data to work on
:type param1: DataFrame
:type param1: :class:`DataFrame`
:param param2: a parameter with different types
:type param2: :class:`int` or :class:`float` or :obj:`None`
:param param3: a optional mapping
Expand Down