mirror of
https://github.com/sphinx-doc/sphinx.git
synced 2025-02-25 18:55:22 -06:00
Related to #1927: [Napoleon] always start description on same line as type in Raises section
This commit is contained in:
Rob Ruana
parent
bfdbee0d04
commit
4670c87be2
@ -321,23 +321,29 @@ class GoogleDocstring(UnicodeMixin):
|
||||
return [prefix]
|
||||
|
||||
def _format_field(self, _name, _type, _desc):
|
||||
separator = (_desc and _desc[0]) and ' --' or ''
|
||||
_desc = self._strip_empty(_desc)
|
||||
has_desc = any(_desc)
|
||||
separator = has_desc and ' -- ' or ''
|
||||
if _name:
|
||||
if _type:
|
||||
if '`' in _type:
|
||||
field = ['**%s** (%s)%s' % (_name, _type, separator)]
|
||||
field = '**%s** (%s)%s' % (_name, _type, separator)
|
||||
else:
|
||||
field = ['**%s** (*%s*)%s' % (_name, _type, separator)]
|
||||
field = '**%s** (*%s*)%s' % (_name, _type, separator)
|
||||
else:
|
||||
field = ['**%s**%s' % (_name, separator)]
|
||||
field = '**%s**%s' % (_name, separator)
|
||||
elif _type:
|
||||
if '`' in _type:
|
||||
field = ['%s%s' % (_type, separator)]
|
||||
field = '%s%s' % (_type, separator)
|
||||
else:
|
||||
field = ['*%s*%s' % (_type, separator)]
|
||||
field = '*%s*%s' % (_type, separator)
|
||||
else:
|
||||
field = []
|
||||
return field + _desc
|
||||
field = ''
|
||||
|
||||
if has_desc:
|
||||
return [field + _desc[0]] + _desc[1:]
|
||||
else:
|
||||
return [field]
|
||||
|
||||
def _format_fields(self, field_type, fields):
|
||||
field_type = ':%s:' % field_type.strip()
|
||||
@ -353,6 +359,8 @@ class GoogleDocstring(UnicodeMixin):
|
||||
lines.extend(self._format_block(field_type + ' * ', field))
|
||||
else:
|
||||
lines.extend(self._format_block(field_type + ' ', field))
|
||||
if lines and lines[-1]:
|
||||
lines.append('')
|
||||
return lines
|
||||
|
||||
def _get_current_indent(self, peek_ahead=0):
|
||||
@ -528,21 +536,22 @@ class GoogleDocstring(UnicodeMixin):
|
||||
multi = len(fields) > 1
|
||||
lines = []
|
||||
for _, _type, _desc in fields:
|
||||
_desc = self._strip_empty(_desc)
|
||||
has_desc = any(_desc)
|
||||
sep = (_desc and _desc[0]) and ' -- ' or ''
|
||||
separator = has_desc and ' -- ' or ''
|
||||
if _type:
|
||||
has_refs = '`' in _type or ':' in _type
|
||||
has_space = any(c in ' \t\n\v\f ' for c in _type)
|
||||
|
||||
if not has_refs and not has_space:
|
||||
_type = ':exc:`%s`%s' % (_type, sep)
|
||||
_type = ':exc:`%s`%s' % (_type, separator)
|
||||
elif has_desc and has_space:
|
||||
_type = '*%s*%s' % (_type, sep)
|
||||
_type = '*%s*%s' % (_type, separator)
|
||||
else:
|
||||
_type = '%s%s' % (_type, sep)
|
||||
_type = '%s%s' % (_type, separator)
|
||||
|
||||
if has_desc:
|
||||
field = [_type] + _desc
|
||||
field = [_type + _desc[0]] + _desc[1:]
|
||||
else:
|
||||
field = [_type]
|
||||
else:
|
||||
@ -585,8 +594,9 @@ class GoogleDocstring(UnicodeMixin):
|
||||
else:
|
||||
lines.extend(self._format_block(':returns: ', field))
|
||||
if _type and use_rtype:
|
||||
lines.append(':rtype: %s' % _type)
|
||||
lines.append('')
|
||||
lines.extend([':rtype: %s' % _type, ''])
|
||||
if lines and lines[-1]:
|
||||
lines.append('')
|
||||
return lines
|
||||
|
||||
def _parse_see_also_section(self, section):
|
||||
|
||||
@ -58,19 +58,15 @@ Sample namedtuple subclass
|
||||
|
||||
.. attribute:: attr1
|
||||
|
||||
*Arbitrary type* --
|
||||
Quick description of attr1
|
||||
*Arbitrary type* -- Quick description of attr1
|
||||
|
||||
.. attribute:: attr2
|
||||
|
||||
*Another arbitrary type* --
|
||||
Quick description of attr2
|
||||
*Another arbitrary type* -- Quick description of attr2
|
||||
|
||||
.. attribute:: attr3
|
||||
|
||||
*Type*
|
||||
""""""
|
||||
Adds a newline after the type
|
||||
*Type* -- Adds a newline after the type
|
||||
"""
|
||||
|
||||
self.assertEqual(expected, actual)
|
||||
@ -103,9 +99,9 @@ class GoogleDocstringTest(BaseDocstringTest):
|
||||
"""
|
||||
Single line summary
|
||||
|
||||
:Parameters: **arg1** (*str*) --
|
||||
Extended
|
||||
description of arg1"""
|
||||
:Parameters: **arg1** (*str*) -- Extended
|
||||
description of arg1
|
||||
"""
|
||||
), (
|
||||
"""
|
||||
Single line summary
|
||||
@ -124,19 +120,16 @@ class GoogleDocstringTest(BaseDocstringTest):
|
||||
"""
|
||||
Single line summary
|
||||
|
||||
:Parameters: * **arg1** (*str*) --
|
||||
Extended
|
||||
:Parameters: * **arg1** (*str*) -- Extended
|
||||
description of arg1
|
||||
* **arg2** (*int*) --
|
||||
Extended
|
||||
* **arg2** (*int*) -- Extended
|
||||
description of arg2
|
||||
|
||||
:Keyword Arguments: * **kwarg1** (*str*) --
|
||||
Extended
|
||||
:Keyword Arguments: * **kwarg1** (*str*) -- Extended
|
||||
description of kwarg1
|
||||
* **kwarg2** (*int*) --
|
||||
Extended
|
||||
description of kwarg2"""
|
||||
* **kwarg2** (*int*) -- Extended
|
||||
description of kwarg2
|
||||
"""
|
||||
), (
|
||||
"""
|
||||
Single line summary
|
||||
@ -155,19 +148,16 @@ class GoogleDocstringTest(BaseDocstringTest):
|
||||
"""
|
||||
Single line summary
|
||||
|
||||
:Parameters: * **arg1** (*str*) --
|
||||
Extended
|
||||
:Parameters: * **arg1** (*str*) -- Extended
|
||||
description of arg1
|
||||
* **arg2** (*int*) --
|
||||
Extended
|
||||
* **arg2** (*int*) -- Extended
|
||||
description of arg2
|
||||
|
||||
:Keyword Arguments: * **kwarg1** (*str*) --
|
||||
Extended
|
||||
:Keyword Arguments: * **kwarg1** (*str*) -- Extended
|
||||
description of kwarg1
|
||||
* **kwarg2** (*int*) --
|
||||
Extended
|
||||
description of kwarg2"""
|
||||
* **kwarg2** (*int*) -- Extended
|
||||
description of kwarg2
|
||||
"""
|
||||
), (
|
||||
"""
|
||||
Single line summary
|
||||
@ -179,9 +169,9 @@ class GoogleDocstringTest(BaseDocstringTest):
|
||||
"""
|
||||
Single line summary
|
||||
|
||||
:returns: *str* --
|
||||
Extended
|
||||
description of return value"""
|
||||
:returns: *str* -- Extended
|
||||
description of return value
|
||||
"""
|
||||
), (
|
||||
"""
|
||||
Single line summary
|
||||
@ -193,9 +183,9 @@ class GoogleDocstringTest(BaseDocstringTest):
|
||||
"""
|
||||
Single line summary
|
||||
|
||||
:returns: *str* --
|
||||
Extended
|
||||
description of return value"""
|
||||
:returns: *str* -- Extended
|
||||
description of return value
|
||||
"""
|
||||
), (
|
||||
"""
|
||||
Single line summary
|
||||
@ -208,7 +198,8 @@ class GoogleDocstringTest(BaseDocstringTest):
|
||||
Single line summary
|
||||
|
||||
:returns: Extended
|
||||
description of return value"""
|
||||
description of return value
|
||||
"""
|
||||
), (
|
||||
"""
|
||||
Single line summary
|
||||
@ -222,13 +213,11 @@ class GoogleDocstringTest(BaseDocstringTest):
|
||||
"""
|
||||
Single line summary
|
||||
|
||||
:Parameters: * **arg1** (*str*) --
|
||||
Extended
|
||||
:Parameters: * **arg1** (*str*) -- Extended
|
||||
description of arg1
|
||||
* **\\*args** --
|
||||
Variable length argument list.
|
||||
* **\\*\\*kwargs** --
|
||||
Arbitrary keyword arguments."""
|
||||
* **\\*args** -- Variable length argument list.
|
||||
* **\\*\\*kwargs** -- Arbitrary keyword arguments.
|
||||
"""
|
||||
), (
|
||||
"""
|
||||
Single line summary
|
||||
@ -240,9 +229,9 @@ class GoogleDocstringTest(BaseDocstringTest):
|
||||
"""
|
||||
Single line summary
|
||||
|
||||
:Yields: *str* --
|
||||
Extended
|
||||
description of yielded value"""
|
||||
:Yields: *str* -- Extended
|
||||
description of yielded value
|
||||
"""
|
||||
), (
|
||||
"""
|
||||
Single line summary
|
||||
@ -255,7 +244,8 @@ class GoogleDocstringTest(BaseDocstringTest):
|
||||
Single line summary
|
||||
|
||||
:Yields: Extended
|
||||
description of yielded value"""
|
||||
description of yielded value
|
||||
"""
|
||||
)]
|
||||
|
||||
def test_docstrings(self):
|
||||
@ -312,8 +302,7 @@ Attributes:
|
||||
expected = """\
|
||||
.. attribute:: in_attr
|
||||
|
||||
:class:`numpy.ndarray` --
|
||||
super-dooper attribute
|
||||
:class:`numpy.ndarray` -- super-dooper attribute
|
||||
"""
|
||||
self.assertEqual(expected, actual)
|
||||
|
||||
@ -326,8 +315,7 @@ Attributes:
|
||||
expected = """\
|
||||
.. attribute:: in_attr
|
||||
|
||||
*numpy.ndarray* --
|
||||
super-dooper attribute
|
||||
*numpy.ndarray* -- super-dooper attribute
|
||||
"""
|
||||
self.assertEqual(expected, actual)
|
||||
|
||||
@ -394,12 +382,8 @@ Raises:
|
||||
""", """
|
||||
Example Function
|
||||
|
||||
:raises: * :exc:`RuntimeError`
|
||||
|
||||
A setting wasn't specified, or was invalid.
|
||||
* :exc:`ValueError`
|
||||
|
||||
Something something value error.
|
||||
:raises: * :exc:`RuntimeError` -- A setting wasn't specified, or was invalid.
|
||||
* :exc:`ValueError` -- Something something value error.
|
||||
"""),
|
||||
################################
|
||||
("""
|
||||
@ -435,8 +419,7 @@ Raises:
|
||||
""", """
|
||||
Example Function
|
||||
|
||||
:raises: *Invalid Dimensions Error* --
|
||||
With description
|
||||
:raises: *Invalid Dimensions Error* -- With description
|
||||
"""),
|
||||
################################
|
||||
("""
|
||||
@ -448,8 +431,7 @@ Raises:
|
||||
""", """
|
||||
Example Function
|
||||
|
||||
:raises: :exc:`InvalidDimensionsError` --
|
||||
If the dimensions couldn't be parsed.
|
||||
:raises: :exc:`InvalidDimensionsError` -- If the dimensions couldn't be parsed.
|
||||
"""),
|
||||
################################
|
||||
("""
|
||||
@ -461,8 +443,7 @@ Raises:
|
||||
""", """
|
||||
Example Function
|
||||
|
||||
:raises: *Invalid Dimensions Error* --
|
||||
If the dimensions couldn't be parsed.
|
||||
:raises: *Invalid Dimensions Error* -- If the dimensions couldn't be parsed.
|
||||
"""),
|
||||
################################
|
||||
("""
|
||||
@ -498,8 +479,8 @@ Raises:
|
||||
""", """
|
||||
Example Function
|
||||
|
||||
:raises: :class:`exc.InvalidDimensionsError` --
|
||||
If the dimensions couldn't be parsed.
|
||||
:raises: :class:`exc.InvalidDimensionsError` -- If the dimensions couldn't """
|
||||
"""be parsed.
|
||||
"""),
|
||||
################################
|
||||
("""
|
||||
@ -512,8 +493,8 @@ Raises:
|
||||
""", """
|
||||
Example Function
|
||||
|
||||
:raises: :class:`exc.InvalidDimensionsError` --
|
||||
If the dimensions couldn't be parsed,
|
||||
:raises: :class:`exc.InvalidDimensionsError` -- If the dimensions couldn't """
|
||||
"""be parsed,
|
||||
then a :class:`exc.InvalidDimensionsError` will be raised.
|
||||
"""),
|
||||
################################
|
||||
@ -527,10 +508,9 @@ Raises:
|
||||
""", """
|
||||
Example Function
|
||||
|
||||
:raises: * :class:`exc.InvalidDimensionsError` --
|
||||
If the dimensions couldn't be parsed.
|
||||
* :class:`exc.InvalidArgumentsError` --
|
||||
If the arguments are invalid.
|
||||
:raises: * :class:`exc.InvalidDimensionsError` -- If the dimensions """
|
||||
"""couldn't be parsed.
|
||||
* :class:`exc.InvalidArgumentsError` -- If the arguments are invalid.
|
||||
"""),
|
||||
################################
|
||||
("""
|
||||
@ -611,9 +591,9 @@ class NumpyDocstringTest(BaseDocstringTest):
|
||||
"""
|
||||
Single line summary
|
||||
|
||||
:Parameters: **arg1** (*str*) --
|
||||
Extended
|
||||
description of arg1"""
|
||||
:Parameters: **arg1** (*str*) -- Extended
|
||||
description of arg1
|
||||
"""
|
||||
), (
|
||||
"""
|
||||
Single line summary
|
||||
@ -639,19 +619,16 @@ class NumpyDocstringTest(BaseDocstringTest):
|
||||
"""
|
||||
Single line summary
|
||||
|
||||
:Parameters: * **arg1** (*str*) --
|
||||
Extended
|
||||
:Parameters: * **arg1** (*str*) -- Extended
|
||||
description of arg1
|
||||
* **arg2** (*int*) --
|
||||
Extended
|
||||
* **arg2** (*int*) -- Extended
|
||||
description of arg2
|
||||
|
||||
:Keyword Arguments: * **kwarg1** (*str*) --
|
||||
Extended
|
||||
:Keyword Arguments: * **kwarg1** (*str*) -- Extended
|
||||
description of kwarg1
|
||||
* **kwarg2** (*int*) --
|
||||
Extended
|
||||
description of kwarg2"""
|
||||
* **kwarg2** (*int*) -- Extended
|
||||
description of kwarg2
|
||||
"""
|
||||
), (
|
||||
"""
|
||||
Single line summary
|
||||
@ -665,9 +642,9 @@ class NumpyDocstringTest(BaseDocstringTest):
|
||||
"""
|
||||
Single line summary
|
||||
|
||||
:returns: *str* --
|
||||
Extended
|
||||
description of return value"""
|
||||
:returns: *str* -- Extended
|
||||
description of return value
|
||||
"""
|
||||
), (
|
||||
"""
|
||||
Single line summary
|
||||
@ -681,9 +658,9 @@ class NumpyDocstringTest(BaseDocstringTest):
|
||||
"""
|
||||
Single line summary
|
||||
|
||||
:returns: *str* --
|
||||
Extended
|
||||
description of return value"""
|
||||
:returns: *str* -- Extended
|
||||
description of return value
|
||||
"""
|
||||
), (
|
||||
"""
|
||||
Single line summary
|
||||
@ -700,12 +677,10 @@ class NumpyDocstringTest(BaseDocstringTest):
|
||||
"""
|
||||
Single line summary
|
||||
|
||||
:Parameters: * **arg1** (*str*) --
|
||||
Extended description of arg1
|
||||
* ***args** --
|
||||
Variable length argument list.
|
||||
* ****kwargs** --
|
||||
Arbitrary keyword arguments."""
|
||||
:Parameters: * **arg1** (*str*) -- Extended description of arg1
|
||||
* ***args** -- Variable length argument list.
|
||||
* ****kwargs** -- Arbitrary keyword arguments.
|
||||
"""
|
||||
), (
|
||||
"""
|
||||
Single line summary
|
||||
@ -719,9 +694,9 @@ class NumpyDocstringTest(BaseDocstringTest):
|
||||
"""
|
||||
Single line summary
|
||||
|
||||
:Yields: *str* --
|
||||
Extended
|
||||
description of yielded value"""
|
||||
:Yields: *str* -- Extended
|
||||
description of yielded value
|
||||
"""
|
||||
), (
|
||||
"""
|
||||
Single line summary
|
||||
@ -735,9 +710,9 @@ class NumpyDocstringTest(BaseDocstringTest):
|
||||
"""
|
||||
Single line summary
|
||||
|
||||
:Yields: *str* --
|
||||
Extended
|
||||
description of yielded value"""
|
||||
:Yields: *str* -- Extended
|
||||
description of yielded value
|
||||
"""
|
||||
)]
|
||||
|
||||
def test_docstrings(self):
|
||||
@ -903,12 +878,8 @@ Raises
|
||||
""", """
|
||||
Example Function
|
||||
|
||||
:raises: * :exc:`RuntimeError`
|
||||
|
||||
A setting wasn't specified, or was invalid.
|
||||
* :exc:`ValueError`
|
||||
|
||||
Something something value error.
|
||||
:raises: * :exc:`RuntimeError` -- A setting wasn't specified, or was invalid.
|
||||
* :exc:`ValueError` -- Something something value error.
|
||||
"""),
|
||||
################################
|
||||
("""
|
||||
@ -948,8 +919,7 @@ Invalid Dimensions Error
|
||||
""", """
|
||||
Example Function
|
||||
|
||||
:raises: *Invalid Dimensions Error* --
|
||||
With description
|
||||
:raises: *Invalid Dimensions Error* -- With description
|
||||
"""),
|
||||
################################
|
||||
("""
|
||||
@ -963,8 +933,7 @@ InvalidDimensionsError
|
||||
""", """
|
||||
Example Function
|
||||
|
||||
:raises: :exc:`InvalidDimensionsError` --
|
||||
If the dimensions couldn't be parsed.
|
||||
:raises: :exc:`InvalidDimensionsError` -- If the dimensions couldn't be parsed.
|
||||
"""),
|
||||
################################
|
||||
("""
|
||||
@ -978,8 +947,7 @@ Invalid Dimensions Error
|
||||
""", """
|
||||
Example Function
|
||||
|
||||
:raises: *Invalid Dimensions Error* --
|
||||
If the dimensions couldn't be parsed.
|
||||
:raises: *Invalid Dimensions Error* -- If the dimensions couldn't be parsed.
|
||||
"""),
|
||||
################################
|
||||
("""
|
||||
@ -1019,8 +987,8 @@ Raises
|
||||
""", """
|
||||
Example Function
|
||||
|
||||
:raises: :class:`exc.InvalidDimensionsError` --
|
||||
If the dimensions couldn't be parsed.
|
||||
:raises: :class:`exc.InvalidDimensionsError` -- If the dimensions couldn't """
|
||||
"""be parsed.
|
||||
"""),
|
||||
################################
|
||||
("""
|
||||
@ -1035,8 +1003,8 @@ Raises
|
||||
""", """
|
||||
Example Function
|
||||
|
||||
:raises: :class:`exc.InvalidDimensionsError` --
|
||||
If the dimensions couldn't be parsed,
|
||||
:raises: :class:`exc.InvalidDimensionsError` -- If the dimensions couldn't """
|
||||
"""be parsed,
|
||||
then a :class:`exc.InvalidDimensionsError` will be raised.
|
||||
"""),
|
||||
################################
|
||||
@ -1053,10 +1021,10 @@ Raises
|
||||
""", """
|
||||
Example Function
|
||||
|
||||
:raises: * :class:`exc.InvalidDimensionsError` --
|
||||
If the dimensions couldn't be parsed.
|
||||
* :class:`exc.InvalidArgumentsError` --
|
||||
If the arguments are invalid.
|
||||
:raises: * :class:`exc.InvalidDimensionsError` -- If the dimensions """
|
||||
"""couldn't be parsed.
|
||||
* :class:`exc.InvalidArgumentsError` -- If the arguments """
|
||||
"""are invalid.
|
||||
"""),
|
||||
################################
|
||||
("""
|
||||
|
||||
Loading…
Reference in New Issue
Block a user