From cac6d1787dff552b7d2617670fcedf815af4a75c Mon Sep 17 00:00:00 2001 From: Keewis Date: Tue, 4 Aug 2020 10:43:31 +0200 Subject: [PATCH 1/2] preprocess even with napoleon_use_param = False --- sphinx/ext/napoleon/docstring.py | 20 ++---- tests/test_ext_napoleon_docstring.py | 96 ++++++++++++++-------------- 2 files changed, 54 insertions(+), 62 deletions(-) diff --git a/sphinx/ext/napoleon/docstring.py b/sphinx/ext/napoleon/docstring.py index 95fb1e538a0..fbf1632e131 100644 --- a/sphinx/ext/napoleon/docstring.py +++ b/sphinx/ext/napoleon/docstring.py @@ -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, @@ -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 {}, + ) if prefer_type and not _type: _type, _name = _name, _type diff --git a/tests/test_ext_napoleon_docstring.py b/tests/test_ext_napoleon_docstring.py index 56812d19390..66ccb75adc7 100644 --- a/tests/test_ext_napoleon_docstring.py +++ b/tests/test_ext_napoleon_docstring.py @@ -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) @@ -1108,7 +1108,7 @@ class NumpyDocstringTest(BaseDocstringTest): """ Single line summary - :Parameters: **arg1** (*str*) -- Extended + :Parameters: **arg1** (:class:`str`) -- Extended description of arg1 """ ), ( @@ -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 """ ), ( @@ -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. """ @@ -1316,7 +1316,7 @@ 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) @@ -1324,7 +1324,7 @@ def test_parameters_without_class_reference(self): actual = str(NumpyDocstring(dedent(docstring), config)) expected = """\ :param param1: -:type param1: MyClass instance +:type param1: :class:`MyClass instance` """ self.assertEqual(expected, actual) @@ -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) @@ -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) @@ -1801,59 +1801,59 @@ 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 @@ -1861,14 +1861,14 @@ def test_list_in_parameter_description(self): 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 @@ -1881,12 +1881,12 @@ 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)) @@ -1894,60 +1894,60 @@ def test_list_in_parameter_description(self): 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 @@ -1955,14 +1955,14 @@ def test_list_in_parameter_description(self): 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 @@ -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 @@ -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 From cb61f0f7341bc3e52e4e3f4f3b7d03d304cfac63 Mon Sep 17 00:00:00 2001 From: Keewis Date: Tue, 4 Aug 2020 11:39:48 +0200 Subject: [PATCH 2/2] document that we don't require use_param = True anymore --- sphinx/ext/napoleon/__init__.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sphinx/ext/napoleon/__init__.py b/sphinx/ext/napoleon/__init__.py index 6d7406ead39..6cab63c9fb7 100644 --- a/sphinx/ext/napoleon/__init__.py +++ b/sphinx/ext/napoleon/__init__.py @@ -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.