mirror of
https://github.com/sphinx-doc/sphinx.git
synced 2025-02-25 18:55:22 -06:00
Fix #2227: [Napoleon] Fixes issue in which bulleted lists in parameter descriptions could cause the sphinx builder to fail
This commit is contained in:
Rob Ruana
@@ -280,14 +280,11 @@ This class should only be used by runtimes.
|
||||
|
||||
:param runtime: Use it to access the environment.
|
||||
It is available in XBlock code as ``self.runtime``.
|
||||
|
||||
:type runtime: :class:`Runtime`
|
||||
:param field_data: Interface used by the XBlock
|
||||
fields to access their data from wherever it is persisted.
|
||||
|
||||
:type field_data: :class:`FieldData`
|
||||
:param scope_ids: Identifiers needed to resolve scopes.
|
||||
|
||||
:type scope_ids: :class:`ScopeIds`
|
||||
"""
|
||||
self.assertEqual(expected, actual)
|
||||
@@ -615,6 +612,285 @@ Summary line
|
||||
actual = str(GoogleDocstring(docstring))
|
||||
self.assertEqual(expected, actual)
|
||||
|
||||
def test_list_in_parameter_description(self):
|
||||
docstring = """One line summary.
|
||||
|
||||
Parameters:
|
||||
no_list (int):
|
||||
one_bullet_empty (int):
|
||||
*
|
||||
one_bullet_single_line (int):
|
||||
- first line
|
||||
one_bullet_two_lines (int):
|
||||
+ first line
|
||||
continued
|
||||
two_bullets_single_line (int):
|
||||
- first line
|
||||
- second line
|
||||
two_bullets_two_lines (int):
|
||||
* first line
|
||||
continued
|
||||
* second line
|
||||
continued
|
||||
one_enumeration_single_line (int):
|
||||
1. first line
|
||||
one_enumeration_two_lines (int):
|
||||
1) first line
|
||||
continued
|
||||
two_enumerations_one_line (int):
|
||||
(iii) first line
|
||||
(iv) second line
|
||||
two_enumerations_two_lines (int):
|
||||
a. first line
|
||||
continued
|
||||
b. second line
|
||||
continued
|
||||
one_definition_one_line (int):
|
||||
item 1
|
||||
first line
|
||||
one_definition_two_lines (int):
|
||||
item 1
|
||||
first line
|
||||
continued
|
||||
two_definitions_one_line (int):
|
||||
item 1
|
||||
first line
|
||||
item 2
|
||||
second line
|
||||
two_definitions_two_lines (int):
|
||||
item 1
|
||||
first line
|
||||
continued
|
||||
item 2
|
||||
second line
|
||||
continued
|
||||
one_definition_blank_line (int):
|
||||
item 1
|
||||
|
||||
first line
|
||||
|
||||
extra first line
|
||||
|
||||
two_definitions_blank_lines (int):
|
||||
item 1
|
||||
|
||||
first line
|
||||
|
||||
extra first line
|
||||
|
||||
item 2
|
||||
|
||||
second line
|
||||
|
||||
extra second line
|
||||
|
||||
definition_after_inline_text (int): text line
|
||||
|
||||
item 1
|
||||
first line
|
||||
|
||||
definition_after_normal_text (int):
|
||||
text line
|
||||
|
||||
item 1
|
||||
first line
|
||||
"""
|
||||
|
||||
expected = """One line summary.
|
||||
|
||||
:param no_list:
|
||||
:type no_list: int
|
||||
:param one_bullet_empty:
|
||||
*
|
||||
:type one_bullet_empty: int
|
||||
:param one_bullet_single_line:
|
||||
- first line
|
||||
:type one_bullet_single_line: int
|
||||
:param one_bullet_two_lines:
|
||||
+ first line
|
||||
continued
|
||||
:type one_bullet_two_lines: int
|
||||
:param two_bullets_single_line:
|
||||
- first line
|
||||
- second line
|
||||
:type two_bullets_single_line: int
|
||||
:param two_bullets_two_lines:
|
||||
* first line
|
||||
continued
|
||||
* second line
|
||||
continued
|
||||
:type two_bullets_two_lines: int
|
||||
:param one_enumeration_single_line:
|
||||
1. first line
|
||||
:type one_enumeration_single_line: int
|
||||
:param one_enumeration_two_lines:
|
||||
1) first line
|
||||
continued
|
||||
:type one_enumeration_two_lines: int
|
||||
:param two_enumerations_one_line:
|
||||
(iii) first line
|
||||
(iv) second line
|
||||
:type two_enumerations_one_line: int
|
||||
:param two_enumerations_two_lines:
|
||||
a. first line
|
||||
continued
|
||||
b. second line
|
||||
continued
|
||||
:type two_enumerations_two_lines: int
|
||||
:param one_definition_one_line:
|
||||
item 1
|
||||
first line
|
||||
:type one_definition_one_line: int
|
||||
:param one_definition_two_lines:
|
||||
item 1
|
||||
first line
|
||||
continued
|
||||
:type one_definition_two_lines: int
|
||||
:param two_definitions_one_line:
|
||||
item 1
|
||||
first line
|
||||
item 2
|
||||
second line
|
||||
:type two_definitions_one_line: int
|
||||
:param two_definitions_two_lines:
|
||||
item 1
|
||||
first line
|
||||
continued
|
||||
item 2
|
||||
second line
|
||||
continued
|
||||
:type two_definitions_two_lines: int
|
||||
:param one_definition_blank_line:
|
||||
item 1
|
||||
|
||||
first line
|
||||
|
||||
extra first line
|
||||
:type one_definition_blank_line: int
|
||||
:param two_definitions_blank_lines:
|
||||
item 1
|
||||
|
||||
first line
|
||||
|
||||
extra first line
|
||||
|
||||
item 2
|
||||
|
||||
second line
|
||||
|
||||
extra second line
|
||||
:type two_definitions_blank_lines: int
|
||||
:param definition_after_inline_text: text line
|
||||
|
||||
item 1
|
||||
first line
|
||||
:type definition_after_inline_text: int
|
||||
:param definition_after_normal_text: text line
|
||||
|
||||
item 1
|
||||
first line
|
||||
:type definition_after_normal_text: int
|
||||
"""
|
||||
config = Config(napoleon_use_param=True)
|
||||
actual = str(GoogleDocstring(docstring, config))
|
||||
self.assertEqual(expected, actual)
|
||||
|
||||
expected = """One line summary.
|
||||
|
||||
:Parameters: * **no_list** (*int*)
|
||||
* **one_bullet_empty** (*int*) --
|
||||
|
||||
*
|
||||
* **one_bullet_single_line** (*int*) --
|
||||
|
||||
- first line
|
||||
* **one_bullet_two_lines** (*int*) --
|
||||
|
||||
+ first line
|
||||
continued
|
||||
* **two_bullets_single_line** (*int*) --
|
||||
|
||||
- first line
|
||||
- second line
|
||||
* **two_bullets_two_lines** (*int*) --
|
||||
|
||||
* first line
|
||||
continued
|
||||
* second line
|
||||
continued
|
||||
* **one_enumeration_single_line** (*int*) --
|
||||
|
||||
1. first line
|
||||
* **one_enumeration_two_lines** (*int*) --
|
||||
|
||||
1) first line
|
||||
continued
|
||||
* **two_enumerations_one_line** (*int*) --
|
||||
|
||||
(iii) first line
|
||||
(iv) second line
|
||||
* **two_enumerations_two_lines** (*int*) --
|
||||
|
||||
a. first line
|
||||
continued
|
||||
b. second line
|
||||
continued
|
||||
* **one_definition_one_line** (*int*) --
|
||||
|
||||
item 1
|
||||
first line
|
||||
* **one_definition_two_lines** (*int*) --
|
||||
|
||||
item 1
|
||||
first line
|
||||
continued
|
||||
* **two_definitions_one_line** (*int*) --
|
||||
|
||||
item 1
|
||||
first line
|
||||
item 2
|
||||
second line
|
||||
* **two_definitions_two_lines** (*int*) --
|
||||
|
||||
item 1
|
||||
first line
|
||||
continued
|
||||
item 2
|
||||
second line
|
||||
continued
|
||||
* **one_definition_blank_line** (*int*) --
|
||||
|
||||
item 1
|
||||
|
||||
first line
|
||||
|
||||
extra first line
|
||||
* **two_definitions_blank_lines** (*int*) --
|
||||
|
||||
item 1
|
||||
|
||||
first line
|
||||
|
||||
extra first line
|
||||
|
||||
item 2
|
||||
|
||||
second line
|
||||
|
||||
extra second line
|
||||
* **definition_after_inline_text** (*int*) -- text line
|
||||
|
||||
item 1
|
||||
first line
|
||||
* **definition_after_normal_text** (*int*) -- text line
|
||||
|
||||
item 1
|
||||
first line
|
||||
"""
|
||||
config = Config(napoleon_use_param=False)
|
||||
actual = str(GoogleDocstring(docstring, config))
|
||||
self.assertEqual(expected, actual)
|
||||
|
||||
|
||||
class NumpyDocstringTest(BaseDocstringTest):
|
||||
docstrings = [(
|
||||
@@ -1194,3 +1470,269 @@ body
|
||||
for docstring, expected in docstrings:
|
||||
actual = str(NumpyDocstring(docstring))
|
||||
self.assertEqual(expected, actual)
|
||||
|
||||
def test_list_in_parameter_description(self):
|
||||
docstring = """One line summary.
|
||||
|
||||
Parameters
|
||||
----------
|
||||
no_list : int
|
||||
one_bullet_empty : int
|
||||
*
|
||||
one_bullet_single_line : int
|
||||
- first line
|
||||
one_bullet_two_lines : int
|
||||
+ first line
|
||||
continued
|
||||
two_bullets_single_line : int
|
||||
- first line
|
||||
- second line
|
||||
two_bullets_two_lines : int
|
||||
* first line
|
||||
continued
|
||||
* second line
|
||||
continued
|
||||
one_enumeration_single_line : int
|
||||
1. first line
|
||||
one_enumeration_two_lines : int
|
||||
1) first line
|
||||
continued
|
||||
two_enumerations_one_line : int
|
||||
(iii) first line
|
||||
(iv) second line
|
||||
two_enumerations_two_lines : int
|
||||
a. first line
|
||||
continued
|
||||
b. second line
|
||||
continued
|
||||
one_definition_one_line : int
|
||||
item 1
|
||||
first line
|
||||
one_definition_two_lines : int
|
||||
item 1
|
||||
first line
|
||||
continued
|
||||
two_definitions_one_line : int
|
||||
item 1
|
||||
first line
|
||||
item 2
|
||||
second line
|
||||
two_definitions_two_lines : int
|
||||
item 1
|
||||
first line
|
||||
continued
|
||||
item 2
|
||||
second line
|
||||
continued
|
||||
one_definition_blank_line : int
|
||||
item 1
|
||||
|
||||
first line
|
||||
|
||||
extra first line
|
||||
|
||||
two_definitions_blank_lines : int
|
||||
item 1
|
||||
|
||||
first line
|
||||
|
||||
extra first line
|
||||
|
||||
item 2
|
||||
|
||||
second line
|
||||
|
||||
extra second line
|
||||
|
||||
definition_after_normal_text : int
|
||||
text line
|
||||
|
||||
item 1
|
||||
first line
|
||||
"""
|
||||
|
||||
expected = """One line summary.
|
||||
|
||||
:param no_list:
|
||||
:type no_list: int
|
||||
:param one_bullet_empty:
|
||||
*
|
||||
:type one_bullet_empty: int
|
||||
:param one_bullet_single_line:
|
||||
- first line
|
||||
:type one_bullet_single_line: int
|
||||
:param one_bullet_two_lines:
|
||||
+ first line
|
||||
continued
|
||||
:type one_bullet_two_lines: int
|
||||
:param two_bullets_single_line:
|
||||
- first line
|
||||
- second line
|
||||
:type two_bullets_single_line: int
|
||||
:param two_bullets_two_lines:
|
||||
* first line
|
||||
continued
|
||||
* second line
|
||||
continued
|
||||
:type two_bullets_two_lines: int
|
||||
:param one_enumeration_single_line:
|
||||
1. first line
|
||||
:type one_enumeration_single_line: int
|
||||
:param one_enumeration_two_lines:
|
||||
1) first line
|
||||
continued
|
||||
:type one_enumeration_two_lines: int
|
||||
:param two_enumerations_one_line:
|
||||
(iii) first line
|
||||
(iv) second line
|
||||
:type two_enumerations_one_line: int
|
||||
:param two_enumerations_two_lines:
|
||||
a. first line
|
||||
continued
|
||||
b. second line
|
||||
continued
|
||||
:type two_enumerations_two_lines: int
|
||||
:param one_definition_one_line:
|
||||
item 1
|
||||
first line
|
||||
:type one_definition_one_line: int
|
||||
:param one_definition_two_lines:
|
||||
item 1
|
||||
first line
|
||||
continued
|
||||
:type one_definition_two_lines: int
|
||||
:param two_definitions_one_line:
|
||||
item 1
|
||||
first line
|
||||
item 2
|
||||
second line
|
||||
:type two_definitions_one_line: int
|
||||
:param two_definitions_two_lines:
|
||||
item 1
|
||||
first line
|
||||
continued
|
||||
item 2
|
||||
second line
|
||||
continued
|
||||
:type two_definitions_two_lines: int
|
||||
:param one_definition_blank_line:
|
||||
item 1
|
||||
|
||||
first line
|
||||
|
||||
extra first line
|
||||
:type one_definition_blank_line: int
|
||||
:param two_definitions_blank_lines:
|
||||
item 1
|
||||
|
||||
first line
|
||||
|
||||
extra first line
|
||||
|
||||
item 2
|
||||
|
||||
second line
|
||||
|
||||
extra second line
|
||||
:type two_definitions_blank_lines: int
|
||||
:param definition_after_normal_text: text line
|
||||
|
||||
item 1
|
||||
first line
|
||||
:type definition_after_normal_text: 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*) --
|
||||
|
||||
*
|
||||
* **one_bullet_single_line** (*int*) --
|
||||
|
||||
- first line
|
||||
* **one_bullet_two_lines** (*int*) --
|
||||
|
||||
+ first line
|
||||
continued
|
||||
* **two_bullets_single_line** (*int*) --
|
||||
|
||||
- first line
|
||||
- second line
|
||||
* **two_bullets_two_lines** (*int*) --
|
||||
|
||||
* first line
|
||||
continued
|
||||
* second line
|
||||
continued
|
||||
* **one_enumeration_single_line** (*int*) --
|
||||
|
||||
1. first line
|
||||
* **one_enumeration_two_lines** (*int*) --
|
||||
|
||||
1) first line
|
||||
continued
|
||||
* **two_enumerations_one_line** (*int*) --
|
||||
|
||||
(iii) first line
|
||||
(iv) second line
|
||||
* **two_enumerations_two_lines** (*int*) --
|
||||
|
||||
a. first line
|
||||
continued
|
||||
b. second line
|
||||
continued
|
||||
* **one_definition_one_line** (*int*) --
|
||||
|
||||
item 1
|
||||
first line
|
||||
* **one_definition_two_lines** (*int*) --
|
||||
|
||||
item 1
|
||||
first line
|
||||
continued
|
||||
* **two_definitions_one_line** (*int*) --
|
||||
|
||||
item 1
|
||||
first line
|
||||
item 2
|
||||
second line
|
||||
* **two_definitions_two_lines** (*int*) --
|
||||
|
||||
item 1
|
||||
first line
|
||||
continued
|
||||
item 2
|
||||
second line
|
||||
continued
|
||||
* **one_definition_blank_line** (*int*) --
|
||||
|
||||
item 1
|
||||
|
||||
first line
|
||||
|
||||
extra first line
|
||||
* **two_definitions_blank_lines** (*int*) --
|
||||
|
||||
item 1
|
||||
|
||||
first line
|
||||
|
||||
extra first line
|
||||
|
||||
item 2
|
||||
|
||||
second line
|
||||
|
||||
extra second line
|
||||
* **definition_after_normal_text** (*int*) -- text line
|
||||
|
||||
item 1
|
||||
first line
|
||||
"""
|
||||
config = Config(napoleon_use_param=False)
|
||||
actual = str(NumpyDocstring(docstring, config))
|
||||
self.assertEqual(expected, actual)
|
||||
|
||||
Reference in New Issue
Block a user