IntenseWebs/sphinx
3
0
Fork 0
mirror of https://github.com/sphinx-doc/sphinx.git synced 2025-02-25 18:55:22 -06:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #8049 from keewis/type-preprocessing-without-use_param

Browse Source 
enable type preprocessing without use_param
This commit is contained in:
Takeshi KOMIYA 2020-08-07 23:37:22 +09:00 committed by GitHub
commit 62a6df8f3c
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
3 changed files with 55 additions and 63 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
sphinx/ext/napoleon/__init__.py
View File

@ -239,7 +239,7 @@ class Config:
napoleon_type_aliases : :obj:`dict` (Defaults to None) napoleon_type_aliases : :obj:`dict` (Defaults to None)
Add a mapping of strings to string, translating types in numpy 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) napoleon_custom_sections : :obj:`list` (Defaults to None)
Add a list of custom sections to include, expanding the list of parsed sections. Add a list of custom sections to include, expanding the list of parsed sections.

20
sphinx/ext/napoleon/docstring.py
View File

@ -956,16 +956,9 @@ def _convert_numpy_type_spec(_type: str, location: str = None, translations: dic
for token in combined_tokens 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 = { converters = {
"literal": lambda x: "``%s``" % x, "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, "control": lambda x: "*%s*" % x,
"delimiter": lambda x: x, "delimiter": lambda x: x,
"reference": lambda x: x, "reference": lambda x: x,
@ -1103,12 +1096,11 @@ class NumpyDocstring(GoogleDocstring):
_name, _type = line, '' _name, _type = line, ''
_name, _type = _name.strip(), _type.strip() _name, _type = _name.strip(), _type.strip()
_name = self._escape_args_and_kwargs(_name) _name = self._escape_args_and_kwargs(_name)
if self._config.napoleon_use_param: _type = _convert_numpy_type_spec(
_type = _convert_numpy_type_spec( _type,
_type, location=self._get_location(),
location=self._get_location(), translations=self._config.napoleon_type_aliases or {},
translations=self._config.napoleon_type_aliases or {}, )
)
if prefer_type and not _type: if prefer_type and not _type:
_type, _name = _name, _type _type, _name = _name, _type

96
tests/test_ext_napoleon_docstring.py
View File

@ -66,19 +66,19 @@ Sample namedtuple subclass
Quick description of attr1 Quick description of attr1
:type: Arbitrary type :type: :class:`Arbitrary type`
.. attribute:: attr2 .. attribute:: attr2
Quick description of attr2 Quick description of attr2
:type: Another arbitrary type :type: :class:`Another arbitrary type`
.. attribute:: attr3 .. attribute:: attr3
Adds a newline after the type Adds a newline after the type
:type: Type :type: :class:`Type`
""" """
self.assertEqual(expected, actual) self.assertEqual(expected, actual)
@ -1126,7 +1126,7 @@ class NumpyDocstringTest(BaseDocstringTest):
""" """
Single line summary Single line summary
:Parameters: **arg1** (*str*) -- Extended :Parameters: **arg1** (:class:`str`) -- Extended
description of arg1 description of arg1
""" """
), ( ), (
@ -1154,14 +1154,14 @@ class NumpyDocstringTest(BaseDocstringTest):
""" """
Single line summary Single line summary
:Parameters: * **arg1** (*str*) -- Extended :Parameters: * **arg1** (:class:`str`) -- Extended
description of arg1 description of arg1
* **arg2** (*int*) -- Extended * **arg2** (:class:`int`) -- Extended
description of arg2 description of arg2
:Keyword Arguments: * **kwarg1** (*str*) -- Extended :Keyword Arguments: * **kwarg1** (:class:`str`) -- Extended
description of kwarg1 description of kwarg1
* **kwarg2** (*int*) -- Extended * **kwarg2** (:class:`int`) -- Extended
description of kwarg2 description of kwarg2
""" """
), ( ), (
@ -1212,7 +1212,7 @@ class NumpyDocstringTest(BaseDocstringTest):
""" """
Single line summary Single line summary
:Parameters: * **arg1** (*str*) -- Extended description of arg1 :Parameters: * **arg1** (:class:`str`) -- Extended description of arg1
* **\\*args** -- Variable length argument list. * **\\*args** -- Variable length argument list.
* **\\*\\*kwargs** -- Arbitrary keyword arguments. * **\\*\\*kwargs** -- Arbitrary keyword arguments.
""" """
@ -1351,7 +1351,7 @@ param1 : MyClass instance
config = Config(napoleon_use_param=False) config = Config(napoleon_use_param=False)
actual = str(NumpyDocstring(docstring, config)) actual = str(NumpyDocstring(docstring, config))
expected = """\ expected = """\
:Parameters: **param1** (*MyClass instance*) :Parameters: **param1** (:class:`MyClass instance`)
""" """
self.assertEqual(expected, actual) self.assertEqual(expected, actual)
@ -1359,7 +1359,7 @@ param1 : MyClass instance
actual = str(NumpyDocstring(dedent(docstring), config)) actual = str(NumpyDocstring(dedent(docstring), config))
expected = """\ expected = """\
:param param1: :param param1:
:type param1: MyClass instance :type param1: :class:`MyClass instance`
""" """
self.assertEqual(expected, actual) self.assertEqual(expected, actual)
@ -1448,7 +1448,7 @@ arg_ : type
expected = """ expected = """
:ivar arg_: some description :ivar arg_: some description
:vartype arg_: type :vartype arg_: :class:`type`
""" """
config = Config(napoleon_use_ivar=True) config = Config(napoleon_use_ivar=True)
@ -1468,7 +1468,7 @@ arg_ : type
expected = """ expected = """
:ivar arg\\_: some description :ivar arg\\_: some description
:vartype arg\\_: type :vartype arg\\_: :class:`type`
""" """
config = Config(napoleon_use_ivar=True) config = Config(napoleon_use_ivar=True)
@ -1836,59 +1836,59 @@ definition_after_normal_text : int
expected = """One line summary. expected = """One line summary.
:param no_list: :param no_list:
:type no_list: int :type no_list: :class:`int`
:param one_bullet_empty: :param one_bullet_empty:
* *
:type one_bullet_empty: int :type one_bullet_empty: :class:`int`
:param one_bullet_single_line: :param one_bullet_single_line:
- first line - first line
:type one_bullet_single_line: int :type one_bullet_single_line: :class:`int`
:param one_bullet_two_lines: :param one_bullet_two_lines:
+ first line + first line
continued continued
:type one_bullet_two_lines: int :type one_bullet_two_lines: :class:`int`
:param two_bullets_single_line: :param two_bullets_single_line:
- first line - first line
- second line - second line
:type two_bullets_single_line: int :type two_bullets_single_line: :class:`int`
:param two_bullets_two_lines: :param two_bullets_two_lines:
* first line * first line
continued continued
* second line * second line
continued continued
:type two_bullets_two_lines: int :type two_bullets_two_lines: :class:`int`
:param one_enumeration_single_line: :param one_enumeration_single_line:
1. first line 1. first line
:type one_enumeration_single_line: int :type one_enumeration_single_line: :class:`int`
:param one_enumeration_two_lines: :param one_enumeration_two_lines:
1) first line 1) first line
continued continued
:type one_enumeration_two_lines: int :type one_enumeration_two_lines: :class:`int`
:param two_enumerations_one_line: :param two_enumerations_one_line:
(iii) first line (iii) first line
(iv) second line (iv) second line
:type two_enumerations_one_line: int :type two_enumerations_one_line: :class:`int`
:param two_enumerations_two_lines: :param two_enumerations_two_lines:
a. first line a. first line
continued continued
b. second line b. second line
continued continued
:type two_enumerations_two_lines: int :type two_enumerations_two_lines: :class:`int`
:param one_definition_one_line: :param one_definition_one_line:
item 1 item 1
first line first line
:type one_definition_one_line: int :type one_definition_one_line: :class:`int`
:param one_definition_two_lines: :param one_definition_two_lines:
item 1 item 1
first line first line
continued continued
:type one_definition_two_lines: int :type one_definition_two_lines: :class:`int`
:param two_definitions_one_line: :param two_definitions_one_line:
item 1 item 1
first line first line
item 2 item 2
second line second line
:type two_definitions_one_line: int :type two_definitions_one_line: :class:`int`
:param two_definitions_two_lines: :param two_definitions_two_lines:
item 1 item 1
first line first line
@ -1896,14 +1896,14 @@ definition_after_normal_text : int
item 2 item 2
second line second line
continued continued
:type two_definitions_two_lines: int :type two_definitions_two_lines: :class:`int`
:param one_definition_blank_line: :param one_definition_blank_line:
item 1 item 1
first line first line
extra first line extra first line
:type one_definition_blank_line: int :type one_definition_blank_line: :class:`int`
:param two_definitions_blank_lines: :param two_definitions_blank_lines:
item 1 item 1
@ -1916,12 +1916,12 @@ definition_after_normal_text : int
second line second line
extra 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 :param definition_after_normal_text: text line
item 1 item 1
first line first line
:type definition_after_normal_text: int :type definition_after_normal_text: :class:`int`
""" """
config = Config(napoleon_use_param=True) config = Config(napoleon_use_param=True)
actual = str(NumpyDocstring(docstring, config)) actual = str(NumpyDocstring(docstring, config))
@ -1929,60 +1929,60 @@ definition_after_normal_text : int
expected = """One line summary. expected = """One line summary.
:Parameters: * **no_list** (*int*) :Parameters: * **no_list** (:class:`int`)
* **one_bullet_empty** (*int*) -- * **one_bullet_empty** (:class:`int`) --
* *
* **one_bullet_single_line** (*int*) -- * **one_bullet_single_line** (:class:`int`) --
- first line - first line
* **one_bullet_two_lines** (*int*) -- * **one_bullet_two_lines** (:class:`int`) --
+ first line + first line
continued continued
* **two_bullets_single_line** (*int*) -- * **two_bullets_single_line** (:class:`int`) --
- first line - first line
- second line - second line
* **two_bullets_two_lines** (*int*) -- * **two_bullets_two_lines** (:class:`int`) --
* first line * first line
continued continued
* second line * second line
continued continued
* **one_enumeration_single_line** (*int*) -- * **one_enumeration_single_line** (:class:`int`) --
1. first line 1. first line
* **one_enumeration_two_lines** (*int*) -- * **one_enumeration_two_lines** (:class:`int`) --
1) first line 1) first line
continued continued
* **two_enumerations_one_line** (*int*) -- * **two_enumerations_one_line** (:class:`int`) --
(iii) first line (iii) first line
(iv) second line (iv) second line
* **two_enumerations_two_lines** (*int*) -- * **two_enumerations_two_lines** (:class:`int`) --
a. first line a. first line
continued continued
b. second line b. second line
continued continued
* **one_definition_one_line** (*int*) -- * **one_definition_one_line** (:class:`int`) --
item 1 item 1
first line first line
* **one_definition_two_lines** (*int*) -- * **one_definition_two_lines** (:class:`int`) --
item 1 item 1
first line first line
continued continued
* **two_definitions_one_line** (*int*) -- * **two_definitions_one_line** (:class:`int`) --
item 1 item 1
first line first line
item 2 item 2
second line second line
* **two_definitions_two_lines** (*int*) -- * **two_definitions_two_lines** (:class:`int`) --
item 1 item 1
first line first line
@ -1990,14 +1990,14 @@ definition_after_normal_text : int
item 2 item 2
second line second line
continued continued
* **one_definition_blank_line** (*int*) -- * **one_definition_blank_line** (:class:`int`) --
item 1 item 1
first line first line
extra first line extra first line
* **two_definitions_blank_lines** (*int*) -- * **two_definitions_blank_lines** (:class:`int`) --
item 1 item 1
@ -2010,7 +2010,7 @@ definition_after_normal_text : int
second line second line
extra second line extra second line
* **definition_after_normal_text** (*int*) -- text line * **definition_after_normal_text** (:class:`int`) -- text line
item 1 item 1
first line first line
@ -2172,7 +2172,7 @@ definition_after_normal_text : int
""") """)
expected = dedent("""\ expected = dedent("""\
:param param1: the data to work on :param param1: the data to work on
:type param1: DataFrame :type param1: :class:`DataFrame`
:param param2: a parameter with different types :param param2: a parameter with different types
:type param2: :class:`int` or :class:`float` or :obj:`None`, *optional* :type param2: :class:`int` or :class:`float` or :obj:`None`, *optional*
:param param3: a optional mapping :param param3: a optional mapping