From 709fb3e1161d6357392e882ababdfc064f04b6ab Mon Sep 17 00:00:00 2001 From: ProGamerGov Date: Sun, 31 Jul 2022 11:09:28 -0600 Subject: [PATCH 01/13] Fix type handling bug --- sphinx/domains/python.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sphinx/domains/python.py b/sphinx/domains/python.py index 99901d2b2b1..366368526d8 100644 --- a/sphinx/domains/python.py +++ b/sphinx/domains/python.py @@ -380,7 +380,7 @@ def make_xrefs(self, rolename: str, domain: str, target: str, innernode: Type[TextlikeNode] = nodes.emphasis, contnode: Node = None, env: BuildEnvironment = None, inliner: Inliner = None, location: Node = None) -> List[Node]: - delims = r'(\s*[\[\]\(\),](?:\s*or\s)?\s*|\s+or\s+|\s*\|\s*|\.\.\.)' + delims = r'(\s*[\[\]\(\),](?:\s*or|of\s)?\s*|\s+or|of\s+|\s*\|\s*|\.\.\.)' delims_re = re.compile(delims) sub_targets = re.split(delims, target) From 47a70f870f8d97715060d323ae85b1df40da25b4 Mon Sep 17 00:00:00 2001 From: Adam Turner <9087854+AA-Turner@users.noreply.github.com> Date: Sun, 31 Jul 2022 20:06:06 +0100 Subject: [PATCH 02/13] Flake8 --- sphinx/domains/python.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sphinx/domains/python.py b/sphinx/domains/python.py index 366368526d8..52a0bb0a14c 100644 --- a/sphinx/domains/python.py +++ b/sphinx/domains/python.py @@ -380,7 +380,7 @@ def make_xrefs(self, rolename: str, domain: str, target: str, innernode: Type[TextlikeNode] = nodes.emphasis, contnode: Node = None, env: BuildEnvironment = None, inliner: Inliner = None, location: Node = None) -> List[Node]: - delims = r'(\s*[\[\]\(\),](?:\s*or|of\s)?\s*|\s+or|of\s+|\s*\|\s*|\.\.\.)' + delims = r'(\s*[\[\]\(\),](?:\s*or|of\s)?\s*|\s+or|of\s+|\s*\|\s*|\.\.\.)' # NoQA: E275, E501 delims_re = re.compile(delims) sub_targets = re.split(delims, target) From 6c5f6c35557000878c0d8481286698cd78a91609 Mon Sep 17 00:00:00 2001 From: Adam Turner <9087854+AA-Turner@users.noreply.github.com> Date: Sun, 31 Jul 2022 20:08:37 +0100 Subject: [PATCH 03/13] Revert Flake8 change, failures unrelated --- sphinx/domains/python.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sphinx/domains/python.py b/sphinx/domains/python.py index 52a0bb0a14c..366368526d8 100644 --- a/sphinx/domains/python.py +++ b/sphinx/domains/python.py @@ -380,7 +380,7 @@ def make_xrefs(self, rolename: str, domain: str, target: str, innernode: Type[TextlikeNode] = nodes.emphasis, contnode: Node = None, env: BuildEnvironment = None, inliner: Inliner = None, location: Node = None) -> List[Node]: - delims = r'(\s*[\[\]\(\),](?:\s*or|of\s)?\s*|\s+or|of\s+|\s*\|\s*|\.\.\.)' # NoQA: E275, E501 + delims = r'(\s*[\[\]\(\),](?:\s*or|of\s)?\s*|\s+or|of\s+|\s*\|\s*|\.\.\.)' delims_re = re.compile(delims) sub_targets = re.split(delims, target) From 38c6da4ac61e3f5a8e5063a18920b6a5f92aa960 Mon Sep 17 00:00:00 2001 From: ProGamerGov Date: Sun, 31 Jul 2022 13:14:35 -0600 Subject: [PATCH 04/13] Fix regex whitespace Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com> --- sphinx/domains/python.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sphinx/domains/python.py b/sphinx/domains/python.py index 366368526d8..b83e22b8f75 100644 --- a/sphinx/domains/python.py +++ b/sphinx/domains/python.py @@ -380,7 +380,7 @@ def make_xrefs(self, rolename: str, domain: str, target: str, innernode: Type[TextlikeNode] = nodes.emphasis, contnode: Node = None, env: BuildEnvironment = None, inliner: Inliner = None, location: Node = None) -> List[Node]: - delims = r'(\s*[\[\]\(\),](?:\s*or|of\s)?\s*|\s+or|of\s+|\s*\|\s*|\.\.\.)' + delims = r'(\s*[\[\]\(\),](?:\s*o[rf]\s)?\s*|\s+o[rf]\s+|\s*\|\s*|\.\.\.)' delims_re = re.compile(delims) sub_targets = re.split(delims, target) From 771ccb181f6b38651fa20811ce4d5a15da23e670 Mon Sep 17 00:00:00 2001 From: ProGamerGov Date: Sun, 31 Jul 2022 18:56:07 -0600 Subject: [PATCH 05/13] Add changes to AUTHORS, CHANGES, & tests --- AUTHORS | 1 + CHANGES | 3 +++ tests/test_ext_napoleon_docstring.py | 31 ++++++++++++++++++++++++++++ 3 files changed, 35 insertions(+) diff --git a/AUTHORS b/AUTHORS index 713082e51a2..a35c27044f0 100644 --- a/AUTHORS +++ b/AUTHORS @@ -30,6 +30,7 @@ Contributors * Antonio Valentino -- qthelp builder, docstring inheritance * Antti Kaihola -- doctest extension (skipif option) * Barry Warsaw -- setup command improvements +* Ben Egan -- Napoleon improvements * Benjamin Peterson -- unittests * Blaise Laflamme -- pyramid theme * Bruce Mitchener -- Minor epub improvement diff --git a/CHANGES b/CHANGES index 90e8b382869..663579287cf 100644 --- a/CHANGES +++ b/CHANGES @@ -13,6 +13,9 @@ Deprecated Features added -------------- +* #10738: napoleon: Add support for docstring types using ``type of type``. + Example: ``tuple of int``. + Bugs fixed ---------- diff --git a/tests/test_ext_napoleon_docstring.py b/tests/test_ext_napoleon_docstring.py index 6db8979320a..683f87ffe59 100644 --- a/tests/test_ext_napoleon_docstring.py +++ b/tests/test_ext_napoleon_docstring.py @@ -356,6 +356,37 @@ class GoogleDocstringTest(BaseDocstringTest): :Yields: Extended description of yielded value """ + ), ( + """ + Single line summary + + Args: + + arg1 (list of str): Extended + description of arg1. + arg2 (tuple of int): Extended + description of arg2. + arg3 (tuple of list of float): Extended + description of arg3. + arg4 (int, float, or list of bool): Extended + description of arg4. + arg5 (list of int, float, or bool): Extended + description of arg5. + """, + """ + Single line summary + + :Parameters: * **arg1** (*list of str*) -- Extended + description of arg1. + * **arg2** (*tuple of int*) -- Extended + description of arg2. + * **arg3** (*tuple of list of float*) -- Extended + description of arg3. + * **arg4** (*int, float, or list of bool*) -- Extended + description of arg4. + * **arg5** (*list of int, float, or bool*) -- Extended + description of arg5. + """ )] def test_sphinx_admonitions(self): From d65d9cd6586182f81adc94c3f80a9aa6e028c98b Mon Sep 17 00:00:00 2001 From: ProGamerGov Date: Sun, 31 Jul 2022 19:25:10 -0600 Subject: [PATCH 06/13] Improve napoleon test case --- tests/test_ext_napoleon_docstring.py | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/tests/test_ext_napoleon_docstring.py b/tests/test_ext_napoleon_docstring.py index 683f87ffe59..1eb03b4f2d9 100644 --- a/tests/test_ext_napoleon_docstring.py +++ b/tests/test_ext_napoleon_docstring.py @@ -372,6 +372,8 @@ class GoogleDocstringTest(BaseDocstringTest): description of arg4. arg5 (list of int, float, or bool): Extended description of arg5. + arg6 (list of int or float): Extended + description of arg6. """, """ Single line summary @@ -386,6 +388,8 @@ class GoogleDocstringTest(BaseDocstringTest): description of arg4. * **arg5** (*list of int, float, or bool*) -- Extended description of arg5. + * **arg6** (*list of int or float*) -- Extended + description of arg6. """ )] From c2e52e6a4aec57e6accc069ed797b7374c5a0cd5 Mon Sep 17 00:00:00 2001 From: ProGamerGov Date: Mon, 1 Aug 2022 08:49:29 -0600 Subject: [PATCH 07/13] Improving testing coverage for napoleon 'of' --- tests/test_ext_napoleon_docstring.py | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/tests/test_ext_napoleon_docstring.py b/tests/test_ext_napoleon_docstring.py index 1eb03b4f2d9..8465e099e99 100644 --- a/tests/test_ext_napoleon_docstring.py +++ b/tests/test_ext_napoleon_docstring.py @@ -2478,6 +2478,7 @@ def test_convert_numpy_type_spec(self): "optional", "str, optional", "int or float or None, default: None", + "list of tuple of str, optional", "int, default None", '{"F", "C", "N"}', "{'F', 'C', 'N'}, default: 'N'", @@ -2490,6 +2491,7 @@ def test_convert_numpy_type_spec(self): "*optional*", ":class:`str`, *optional*", ":class:`int` or :class:`float` or :obj:`None`, *default*: :obj:`None`", + ":class:`list` of :class:`tuple` of :class:`str`, *optional*", ":class:`int`, *default* :obj:`None`", '``{"F", "C", "N"}``', "``{'F', 'C', 'N'}``, *default*: ``'N'``", @@ -2521,6 +2523,8 @@ def test_parameter_types(self): a optional mapping param8 : ... or Ellipsis ellipsis + param9 : tuple of list of int + a parameter with tuple of list of int """) expected = dedent("""\ :param param1: the data to work on @@ -2539,6 +2543,8 @@ def test_parameter_types(self): :type param7: :term:`mapping` of :term:`hashable` to :class:`str`, *optional* :param param8: ellipsis :type param8: :obj:`... ` or :obj:`Ellipsis` + :param param9: a parameter with tuple of list of int + :type param9: :class:`tuple` of :class:`list` of :class:`int` """) translations = { "dict-like": ":term:`dict-like `", From d37e8410357c228111a0d8fac83254f5823400b9 Mon Sep 17 00:00:00 2001 From: ProGamerGov Date: Mon, 1 Aug 2022 13:09:16 -0600 Subject: [PATCH 08/13] Improve testing coverage --- tests/test_ext_napoleon_docstring.py | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/tests/test_ext_napoleon_docstring.py b/tests/test_ext_napoleon_docstring.py index 8465e099e99..c2704ebce26 100644 --- a/tests/test_ext_napoleon_docstring.py +++ b/tests/test_ext_napoleon_docstring.py @@ -2402,6 +2402,8 @@ def test_tokenize_type_spec(self): "defaultdict", "int, float, or complex", "int or float or None, optional", + "list of list of int or float, optional", + "tuple of list of str, float, or int", '{"F", "C", "N"}', "{'F', 'C', 'N'}, default: 'F'", "{'F', 'C', 'N or C'}, default 'F'", @@ -2418,6 +2420,8 @@ def test_tokenize_type_spec(self): ["defaultdict"], ["int", ", ", "float", ", or ", "complex"], ["int", " or ", "float", " or ", "None", ", ", "optional"], + ["list", " of ", "list", " of ", "int", " or ", "float", ", ", "optional"], + ["tuple", " of ", "list", " of ", "str", ", ", "float", ", or ", "int"], ["{", '"F"', ", ", '"C"', ", ", '"N"', "}"], ["{", "'F'", ", ", "'C'", ", ", "'N'", "}", ", ", "default", ": ", "'F'"], ["{", "'F'", ", ", "'C'", ", ", "'N or C'", "}", ", ", "default", " ", "'F'"], From 94f6603f07699e6d0a4d58bc0a8de304e825925a Mon Sep 17 00:00:00 2001 From: ProGamerGov Date: Tue, 2 Aug 2022 13:23:11 -0600 Subject: [PATCH 09/13] Add delineator tests to Python domain testing --- tests/test_domain_py.py | 72 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 72 insertions(+) diff --git a/tests/test_domain_py.py b/tests/test_domain_py.py index 26f12e48ceb..b58b9c0de0c 100644 --- a/tests/test_domain_py.py +++ b/tests/test_domain_py.py @@ -1214,6 +1214,78 @@ def test_info_field_list_var(app): refdomain="py", reftype="class", reftarget="int", **{"py:class": "Class"}) +def test_info_field_list_napoleon_deliminator_of(app): + text = (".. py:module:: example\n" + ".. py:class:: Class\n" + "\n" + " :param list_str_var: example description.\n" + " :type list_str_var: list of str\n" + " :param tuple_int_var: example description.\n" + " :type tuple_int_var: tuple of tuple of int\n" + ) + doctree = restructuredtext.parse(app, text) + + # :param list of str list_str_var: + assert_node(doctree[3][1][0][0][1][0][0][0], + ([addnodes.literal_strong, "list_str_var"], + " (", + [pending_xref, addnodes.literal_emphasis, "list"], + [addnodes.literal_emphasis, " of "], + [pending_xref, addnodes.literal_emphasis, "str"], + ")", + " -- ", + "example description.")) + + # :param tuple of tuple of int tuple_int_var: + assert_node(doctree[3][1][0][0][1][0][1][0], + ([addnodes.literal_strong, "tuple_int_var"], + " (", + [pending_xref, addnodes.literal_emphasis, "tuple"], + [addnodes.literal_emphasis, " of "], + [pending_xref, addnodes.literal_emphasis, "tuple"], + [addnodes.literal_emphasis, " of "], + [pending_xref, addnodes.literal_emphasis, "int"], + ")", + " -- ", + "example description.")) + + +def test_info_field_list_napoleon_deliminator_or(app): + text = (".. py:module:: example\n" + ".. py:class:: Class\n" + "\n" + " :param bool_str_var: example description.\n" + " :type bool_str_var: bool or str\n" + " :param str_float_int_var: example description.\n" + " :type str_float_int_var: str or float or int\n" + ) + doctree = restructuredtext.parse(app, text) + + # :param bool or str bool_str_var: + assert_node(doctree[3][1][0][0][1][0][0][0], + ([addnodes.literal_strong, "bool_str_var"], + " (", + [pending_xref, addnodes.literal_emphasis, "bool"], + [addnodes.literal_emphasis, " or "], + [pending_xref, addnodes.literal_emphasis, "str"], + ")", + " -- ", + "example description.")) + + # :param str or float or int str_float_int_var: + assert_node(doctree[3][1][0][0][1][0][1][0], + ([addnodes.literal_strong, "str_float_int_var"], + " (", + [pending_xref, addnodes.literal_emphasis, "str"], + [addnodes.literal_emphasis, " or "], + [pending_xref, addnodes.literal_emphasis, "float"], + [addnodes.literal_emphasis, " or "], + [pending_xref, addnodes.literal_emphasis, "int"], + ")", + " -- ", + "example description.")) + + def test_type_field(app): text = (".. py:data:: var1\n" " :type: .int\n" From 5c35a567b9e851dbf2f94cf24ecae3832dac4b7f Mon Sep 17 00:00:00 2001 From: ProGamerGov Date: Tue, 2 Aug 2022 13:29:47 -0600 Subject: [PATCH 10/13] Update CHANGES --- CHANGES | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/CHANGES b/CHANGES index 663579287cf..2516243a624 100644 --- a/CHANGES +++ b/CHANGES @@ -13,8 +13,8 @@ Deprecated Features added -------------- -* #10738: napoleon: Add support for docstring types using ``type of type``. - Example: ``tuple of int``. +* #10738: napoleon: Add support for docstring types using 'of', like + ``type of type``. Example: ``tuple of int``. Bugs fixed ---------- From db374c8520f033a42ad451f85c84560044957749 Mon Sep 17 00:00:00 2001 From: ProGamerGov Date: Tue, 2 Aug 2022 13:34:51 -0600 Subject: [PATCH 11/13] Add bugfix line --- CHANGES | 3 +++ 1 file changed, 3 insertions(+) diff --git a/CHANGES b/CHANGES index 2516243a624..8cbb90f787e 100644 --- a/CHANGES +++ b/CHANGES @@ -21,6 +21,9 @@ Bugs fixed * #10723: LaTeX: 5.1.0 has made the 'sphinxsetup' ``verbatimwithframe=false`` become without effect. +* #10738: napoleon: Added testing for docstring types using 'or' in the + python domain, like ``type or type``. Previously this functionality wasn't + being tested. Testing -------- From 7e7f25df5833c92f9d7856e6c40ecf868fe47633 Mon Sep 17 00:00:00 2001 From: ProGamerGov Date: Tue, 2 Aug 2022 13:35:31 -0600 Subject: [PATCH 12/13] Fix bug fix line --- CHANGES | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CHANGES b/CHANGES index 8cbb90f787e..823b052d5fb 100644 --- a/CHANGES +++ b/CHANGES @@ -21,7 +21,7 @@ Bugs fixed * #10723: LaTeX: 5.1.0 has made the 'sphinxsetup' ``verbatimwithframe=false`` become without effect. -* #10738: napoleon: Added testing for docstring types using 'or' in the +* #10738: py domain: Added testing for docstring types using 'or' in the python domain, like ``type or type``. Previously this functionality wasn't being tested. From 2957f434f3aa1fe740958852a273ae6c131d1a19 Mon Sep 17 00:00:00 2001 From: ProGamerGov Date: Tue, 2 Aug 2022 16:28:45 -0600 Subject: [PATCH 13/13] Fix flake8 error --- CHANGES | 3 --- tests/test_domain_py.py | 4 ++-- 2 files changed, 2 insertions(+), 5 deletions(-) diff --git a/CHANGES b/CHANGES index 823b052d5fb..2516243a624 100644 --- a/CHANGES +++ b/CHANGES @@ -21,9 +21,6 @@ Bugs fixed * #10723: LaTeX: 5.1.0 has made the 'sphinxsetup' ``verbatimwithframe=false`` become without effect. -* #10738: py domain: Added testing for docstring types using 'or' in the - python domain, like ``type or type``. Previously this functionality wasn't - being tested. Testing -------- diff --git a/tests/test_domain_py.py b/tests/test_domain_py.py index b58b9c0de0c..9e9cd4fb3a2 100644 --- a/tests/test_domain_py.py +++ b/tests/test_domain_py.py @@ -1222,7 +1222,7 @@ def test_info_field_list_napoleon_deliminator_of(app): " :type list_str_var: list of str\n" " :param tuple_int_var: example description.\n" " :type tuple_int_var: tuple of tuple of int\n" - ) + ) doctree = restructuredtext.parse(app, text) # :param list of str list_str_var: @@ -1258,7 +1258,7 @@ def test_info_field_list_napoleon_deliminator_or(app): " :type bool_str_var: bool or str\n" " :param str_float_int_var: example description.\n" " :type str_float_int_var: str or float or int\n" - ) + ) doctree = restructuredtext.parse(app, text) # :param bool or str bool_str_var: