Skip to content

Commit

Permalink
Merge pull request #8049 from keewis/type-preprocessing-without-use_p…
Browse files Browse the repository at this point in the history 
…aram

enable type preprocessing without use_param
  • Loading branch information
@tk0miya
tk0miya committed Aug 7, 2020
2 parents 92a134b + cb61f0f commit 62a6df8
Show file tree
Hide file tree
Showing 3 changed files with 55 additions and 63 deletions.
2 changes: 1 addition & 1 deletion sphinx/ext/napoleon/__init__.py
View file
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
Expand Up @@ -956,16 +956,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 @@ -1103,12 +1096,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 {},
)

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
Expand Up @@ -66,19 +66,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 @@ -1126,7 +1126,7 @@ class NumpyDocstringTest(BaseDocstringTest):
"""
Single line summary
:Parameters: **arg1** (*str*) -- Extended
:Parameters: **arg1** (:class:`str`) -- Extended
description of arg1
"""
), (
Expand Down Expand Up @@ -1154,14 +1154,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 @@ -1212,7 +1212,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 @@ -1351,15 +1351,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 @@ -1448,7 +1448,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 @@ -1468,7 +1468,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 @@ -1836,74 +1836,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 @@ -1916,88 +1916,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 @@ -2010,7 +2010,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 @@ -2172,7 +2172,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`, *optional*
:param param3: a optional mapping
Expand Down

0 comments on commit 62a6df8

Please sign in to comment.