mirror of
https://github.com/sphinx-doc/sphinx.git
synced 2025-02-25 18:55:22 -06:00
Merge pull request #8049 from keewis/type-preprocessing-without-use_param
enable type preprocessing without use_param
This commit is contained in:
Takeshi KOMIYA
GitHub
commit
62a6df8f3c
@ -239,7 +239,7 @@ class Config:
|
||||
|
||||
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.
|
||||
|
||||
@ -956,16 +956,9 @@ def _convert_numpy_type_spec(_type: str, location: str = None, translations: dic
|
||||
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,
|
||||
@ -1103,12 +1096,11 @@ class NumpyDocstring(GoogleDocstring):
|
||||
_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
|
||||
|
||||
@ -66,19 +66,19 @@ Sample namedtuple subclass
|
||||
|
||||
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)
|
||||
@ -1126,7 +1126,7 @@ class NumpyDocstringTest(BaseDocstringTest):
|
||||
"""
|
||||
Single line summary
|
||||
|
||||
:Parameters: **arg1** (*str*) -- Extended
|
||||
:Parameters: **arg1** (:class:`str`) -- Extended
|
||||
description of arg1
|
||||
"""
|
||||
), (
|
||||
@ -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
|
||||
"""
|
||||
), (
|
||||
@ -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.
|
||||
"""
|
||||
@ -1351,7 +1351,7 @@ param1 : MyClass instance
|
||||
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)
|
||||
|
||||
@ -1359,7 +1359,7 @@ param1 : MyClass instance
|
||||
actual = str(NumpyDocstring(dedent(docstring), config))
|
||||
expected = """\
|
||||
:param param1:
|
||||
:type param1: MyClass instance
|
||||
:type param1: :class:`MyClass instance`
|
||||
"""
|
||||
self.assertEqual(expected, actual)
|
||||
|
||||
@ -1448,7 +1448,7 @@ arg_ : type
|
||||
|
||||
expected = """
|
||||
:ivar arg_: some description
|
||||
:vartype arg_: type
|
||||
:vartype arg_: :class:`type`
|
||||
"""
|
||||
|
||||
config = Config(napoleon_use_ivar=True)
|
||||
@ -1468,7 +1468,7 @@ arg_ : type
|
||||
|
||||
expected = """
|
||||
:ivar arg\\_: some description
|
||||
:vartype arg\\_: type
|
||||
:vartype arg\\_: :class:`type`
|
||||
"""
|
||||
|
||||
config = Config(napoleon_use_ivar=True)
|
||||
@ -1836,59 +1836,59 @@ definition_after_normal_text : int
|
||||
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
|
||||
@ -1896,14 +1896,14 @@ definition_after_normal_text : int
|
||||
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
|
||||
|
||||
@ -1916,12 +1916,12 @@ definition_after_normal_text : int
|
||||
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))
|
||||
@ -1929,60 +1929,60 @@ definition_after_normal_text : int
|
||||
|
||||
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
|
||||
@ -1990,14 +1990,14 @@ definition_after_normal_text : int
|
||||
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
|
||||
|
||||
@ -2010,7 +2010,7 @@ definition_after_normal_text : int
|
||||
second line
|
||||
|
||||
extra second line
|
||||
* **definition_after_normal_text** (*int*) -- text line
|
||||
* **definition_after_normal_text** (:class:`int`) -- text line
|
||||
|
||||
item 1
|
||||
first line
|
||||
@ -2172,7 +2172,7 @@ definition_after_normal_text : int
|
||||
""")
|
||||
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
|
||||
|
||||
Loading…
Reference in New Issue
Block a user