IntenseWebs/sphinx
3
0
Fork 0
mirror of https://github.com/sphinx-doc/sphinx.git synced 2025-02-25 18:55:22 -06:00
Code Issues Packages Projects Releases Wiki Activity

Related to #1927: [Napoleon] always start description on same line as type in Raises section

Browse Source
This commit is contained in:
Rob Ruana
2015-06-11 12:50:05 -07:00
parent bfdbee0d04
commit 4670c87be2
2 changed files with 112 additions and 134 deletions
Download Patch File Download Diff File Expand all files Collapse all files

40
sphinx/ext/napoleon/docstring.py
View File

@@ -321,23 +321,29 @@ class GoogleDocstring(UnicodeMixin):
return [prefix] return [prefix]
def _format_field(self, _name, _type, _desc): 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 _name:
if _type: if _type:
if '`' in _type: if '`' in _type:
field = ['**%s** (%s)%s' % (_name, _type, separator)] field = '**%s** (%s)%s' % (_name, _type, separator)
else: else:
field = ['**%s** (*%s*)%s' % (_name, _type, separator)] field = '**%s** (*%s*)%s' % (_name, _type, separator)
else: else:
field = ['**%s**%s' % (_name, separator)] field = '**%s**%s' % (_name, separator)
elif _type: elif _type:
if '`' in _type: if '`' in _type:
field = ['%s%s' % (_type, separator)] field = '%s%s' % (_type, separator)
else: else:
field = ['*%s*%s' % (_type, separator)] field = '*%s*%s' % (_type, separator)
else: else:
field = [] field = ''
return field + _desc
if has_desc:
return [field + _desc[0]] + _desc[1:]
else:
return [field]
def _format_fields(self, field_type, fields): def _format_fields(self, field_type, fields):
field_type = ':%s:' % field_type.strip() field_type = ':%s:' % field_type.strip()
@@ -353,6 +359,8 @@ class GoogleDocstring(UnicodeMixin):
lines.extend(self._format_block(field_type + ' * ', field)) lines.extend(self._format_block(field_type + ' * ', field))
else: else:
lines.extend(self._format_block(field_type + ' ', field)) lines.extend(self._format_block(field_type + ' ', field))
if lines and lines[-1]:
lines.append('')
return lines return lines
def _get_current_indent(self, peek_ahead=0): def _get_current_indent(self, peek_ahead=0):
@@ -528,21 +536,22 @@ class GoogleDocstring(UnicodeMixin):
multi = len(fields) > 1 multi = len(fields) > 1
lines = [] lines = []
for _, _type, _desc in fields: for _, _type, _desc in fields:
_desc = self._strip_empty(_desc)
has_desc = any(_desc) has_desc = any(_desc)
sep = (_desc and _desc[0]) and ' -- ' or '' separator = has_desc and ' -- ' or ''
if _type: if _type:
has_refs = '`' in _type or ':' in _type has_refs = '`' in _type or ':' in _type
has_space = any(c in ' \t\n\v\f ' for c in _type) has_space = any(c in ' \t\n\v\f ' for c in _type)
if not has_refs and not has_space: 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: elif has_desc and has_space:
_type = '*%s*%s' % (_type, sep) _type = '*%s*%s' % (_type, separator)
else: else:
_type = '%s%s' % (_type, sep) _type = '%s%s' % (_type, separator)
if has_desc: if has_desc:
field = [_type] + _desc field = [_type + _desc[0]] + _desc[1:]
else: else:
field = [_type] field = [_type]
else: else:
@@ -585,8 +594,9 @@ class GoogleDocstring(UnicodeMixin):
else: else:
lines.extend(self._format_block(':returns: ', field)) lines.extend(self._format_block(':returns: ', field))
if _type and use_rtype: if _type and use_rtype:
lines.append(':rtype: %s' % _type) lines.extend([':rtype: %s' % _type, ''])
lines.append('') if lines and lines[-1]:
lines.append('')
return lines return lines
def _parse_see_also_section(self, section): def _parse_see_also_section(self, section):

206
tests/test_ext_napoleon_docstring.py
View File

@@ -58,19 +58,15 @@ Sample namedtuple subclass
.. attribute:: attr1 .. attribute:: attr1
*Arbitrary type* -- *Arbitrary type* -- Quick description of attr1
Quick description of attr1
.. attribute:: attr2 .. attribute:: attr2
*Another arbitrary type* -- *Another arbitrary type* -- Quick description of attr2
Quick description of attr2
.. attribute:: attr3 .. attribute:: attr3
*Type* *Type* -- Adds a newline after the type
""""""
Adds a newline after the type
""" """
self.assertEqual(expected, actual) self.assertEqual(expected, actual)
@@ -103,9 +99,9 @@ class GoogleDocstringTest(BaseDocstringTest):
""" """
Single line summary Single line summary
:Parameters: **arg1** (*str*) -- :Parameters: **arg1** (*str*) -- Extended
Extended description of arg1
description of arg1""" """
), ( ), (
""" """
Single line summary Single line summary
@@ -124,19 +120,16 @@ class GoogleDocstringTest(BaseDocstringTest):
""" """
Single line summary Single line summary
:Parameters: * **arg1** (*str*) -- :Parameters: * **arg1** (*str*) -- Extended
Extended
description of arg1 description of arg1
* **arg2** (*int*) -- * **arg2** (*int*) -- Extended
Extended
description of arg2 description of arg2
:Keyword Arguments: * **kwarg1** (*str*) -- :Keyword Arguments: * **kwarg1** (*str*) -- Extended
Extended
description of kwarg1 description of kwarg1
* **kwarg2** (*int*) -- * **kwarg2** (*int*) -- Extended
Extended description of kwarg2
description of kwarg2""" """
), ( ), (
""" """
Single line summary Single line summary
@@ -155,19 +148,16 @@ class GoogleDocstringTest(BaseDocstringTest):
""" """
Single line summary Single line summary
:Parameters: * **arg1** (*str*) -- :Parameters: * **arg1** (*str*) -- Extended
Extended
description of arg1 description of arg1
* **arg2** (*int*) -- * **arg2** (*int*) -- Extended
Extended
description of arg2 description of arg2
:Keyword Arguments: * **kwarg1** (*str*) -- :Keyword Arguments: * **kwarg1** (*str*) -- Extended
Extended
description of kwarg1 description of kwarg1
* **kwarg2** (*int*) -- * **kwarg2** (*int*) -- Extended
Extended description of kwarg2
description of kwarg2""" """
), ( ), (
""" """
Single line summary Single line summary
@@ -179,9 +169,9 @@ class GoogleDocstringTest(BaseDocstringTest):
""" """
Single line summary Single line summary
:returns: *str* -- :returns: *str* -- Extended
Extended description of return value
description of return value""" """
), ( ), (
""" """
Single line summary Single line summary
@@ -193,9 +183,9 @@ class GoogleDocstringTest(BaseDocstringTest):
""" """
Single line summary Single line summary
:returns: *str* -- :returns: *str* -- Extended
Extended description of return value
description of return value""" """
), ( ), (
""" """
Single line summary Single line summary
@@ -208,7 +198,8 @@ class GoogleDocstringTest(BaseDocstringTest):
Single line summary Single line summary
:returns: Extended :returns: Extended
description of return value""" description of return value
"""
), ( ), (
""" """
Single line summary Single line summary
@@ -222,13 +213,11 @@ class GoogleDocstringTest(BaseDocstringTest):
""" """
Single line summary Single line summary
:Parameters: * **arg1** (*str*) -- :Parameters: * **arg1** (*str*) -- Extended
Extended
description of arg1 description of arg1
* **\\*args** -- * **\\*args** -- Variable length argument list.
Variable length argument list. * **\\*\\*kwargs** -- Arbitrary keyword arguments.
* **\\*\\*kwargs** -- """
Arbitrary keyword arguments."""
), ( ), (
""" """
Single line summary Single line summary
@@ -240,9 +229,9 @@ class GoogleDocstringTest(BaseDocstringTest):
""" """
Single line summary Single line summary
:Yields: *str* -- :Yields: *str* -- Extended
Extended description of yielded value
description of yielded value""" """
), ( ), (
""" """
Single line summary Single line summary
@@ -255,7 +244,8 @@ class GoogleDocstringTest(BaseDocstringTest):
Single line summary Single line summary
:Yields: Extended :Yields: Extended
description of yielded value""" description of yielded value
"""
)] )]
def test_docstrings(self): def test_docstrings(self):
@@ -312,8 +302,7 @@ Attributes:
expected = """\ expected = """\
.. attribute:: in_attr .. attribute:: in_attr
:class:`numpy.ndarray` -- :class:`numpy.ndarray` -- super-dooper attribute
super-dooper attribute
""" """
self.assertEqual(expected, actual) self.assertEqual(expected, actual)
@@ -326,8 +315,7 @@ Attributes:
expected = """\ expected = """\
.. attribute:: in_attr .. attribute:: in_attr
*numpy.ndarray* -- *numpy.ndarray* -- super-dooper attribute
super-dooper attribute
""" """
self.assertEqual(expected, actual) self.assertEqual(expected, actual)
@@ -394,12 +382,8 @@ Raises:
""", """ """, """
Example Function Example Function
:raises: * :exc:`RuntimeError` :raises: * :exc:`RuntimeError` -- A setting wasn't specified, or was invalid.
* :exc:`ValueError` -- Something something value error.
A setting wasn't specified, or was invalid.
* :exc:`ValueError`
Something something value error.
"""), """),
################################ ################################
(""" ("""
@@ -435,8 +419,7 @@ Raises:
""", """ """, """
Example Function Example Function
:raises: *Invalid Dimensions Error* -- :raises: *Invalid Dimensions Error* -- With description
With description
"""), """),
################################ ################################
(""" ("""
@@ -448,8 +431,7 @@ Raises:
""", """ """, """
Example Function Example Function
:raises: :exc:`InvalidDimensionsError` -- :raises: :exc:`InvalidDimensionsError` -- If the dimensions couldn't be parsed.
If the dimensions couldn't be parsed.
"""), """),
################################ ################################
(""" ("""
@@ -461,8 +443,7 @@ Raises:
""", """ """, """
Example Function Example Function
:raises: *Invalid Dimensions Error* -- :raises: *Invalid Dimensions Error* -- If the dimensions couldn't be parsed.
If the dimensions couldn't be parsed.
"""), """),
################################ ################################
(""" ("""
@@ -498,8 +479,8 @@ Raises:
""", """ """, """
Example Function Example Function
:raises: :class:`exc.InvalidDimensionsError` -- :raises: :class:`exc.InvalidDimensionsError` -- If the dimensions couldn't """
If the dimensions couldn't be parsed. """be parsed.
"""), """),
################################ ################################
(""" ("""
@@ -512,8 +493,8 @@ Raises:
""", """ """, """
Example Function Example Function
:raises: :class:`exc.InvalidDimensionsError` -- :raises: :class:`exc.InvalidDimensionsError` -- If the dimensions couldn't """
If the dimensions couldn't be parsed, """be parsed,
then a :class:`exc.InvalidDimensionsError` will be raised. then a :class:`exc.InvalidDimensionsError` will be raised.
"""), """),
################################ ################################
@@ -527,10 +508,9 @@ Raises:
""", """ """, """
Example Function Example Function
:raises: * :class:`exc.InvalidDimensionsError` -- :raises: * :class:`exc.InvalidDimensionsError` -- If the dimensions """
If the dimensions couldn't be parsed. """couldn't be parsed.
* :class:`exc.InvalidArgumentsError` -- * :class:`exc.InvalidArgumentsError` -- If the arguments are invalid.
If the arguments are invalid.
"""), """),
################################ ################################
(""" ("""
@@ -611,9 +591,9 @@ class NumpyDocstringTest(BaseDocstringTest):
""" """
Single line summary Single line summary
:Parameters: **arg1** (*str*) -- :Parameters: **arg1** (*str*) -- Extended
Extended description of arg1
description of arg1""" """
), ( ), (
""" """
Single line summary Single line summary
@@ -639,19 +619,16 @@ class NumpyDocstringTest(BaseDocstringTest):
""" """
Single line summary Single line summary
:Parameters: * **arg1** (*str*) -- :Parameters: * **arg1** (*str*) -- Extended
Extended
description of arg1 description of arg1
* **arg2** (*int*) -- * **arg2** (*int*) -- Extended
Extended
description of arg2 description of arg2
:Keyword Arguments: * **kwarg1** (*str*) -- :Keyword Arguments: * **kwarg1** (*str*) -- Extended
Extended
description of kwarg1 description of kwarg1
* **kwarg2** (*int*) -- * **kwarg2** (*int*) -- Extended
Extended description of kwarg2
description of kwarg2""" """
), ( ), (
""" """
Single line summary Single line summary
@@ -665,9 +642,9 @@ class NumpyDocstringTest(BaseDocstringTest):
""" """
Single line summary Single line summary
:returns: *str* -- :returns: *str* -- Extended
Extended description of return value
description of return value""" """
), ( ), (
""" """
Single line summary Single line summary
@@ -681,9 +658,9 @@ class NumpyDocstringTest(BaseDocstringTest):
""" """
Single line summary Single line summary
:returns: *str* -- :returns: *str* -- Extended
Extended description of return value
description of return value""" """
), ( ), (
""" """
Single line summary Single line summary
@@ -700,12 +677,10 @@ class NumpyDocstringTest(BaseDocstringTest):
""" """
Single line summary Single line summary
:Parameters: * **arg1** (*str*) -- :Parameters: * **arg1** (*str*) -- Extended description of arg1
Extended description of arg1 * ***args** -- Variable length argument list.
* ***args** -- * ****kwargs** -- Arbitrary keyword arguments.
Variable length argument list. """
* ****kwargs** --
Arbitrary keyword arguments."""
), ( ), (
""" """
Single line summary Single line summary
@@ -719,9 +694,9 @@ class NumpyDocstringTest(BaseDocstringTest):
""" """
Single line summary Single line summary
:Yields: *str* -- :Yields: *str* -- Extended
Extended description of yielded value
description of yielded value""" """
), ( ), (
""" """
Single line summary Single line summary
@@ -735,9 +710,9 @@ class NumpyDocstringTest(BaseDocstringTest):
""" """
Single line summary Single line summary
:Yields: *str* -- :Yields: *str* -- Extended
Extended description of yielded value
description of yielded value""" """
)] )]
def test_docstrings(self): def test_docstrings(self):
@@ -903,12 +878,8 @@ Raises
""", """ """, """
Example Function Example Function
:raises: * :exc:`RuntimeError` :raises: * :exc:`RuntimeError` -- A setting wasn't specified, or was invalid.
* :exc:`ValueError` -- Something something value error.
A setting wasn't specified, or was invalid.
* :exc:`ValueError`
Something something value error.
"""), """),
################################ ################################
(""" ("""
@@ -948,8 +919,7 @@ Invalid Dimensions Error
""", """ """, """
Example Function Example Function
:raises: *Invalid Dimensions Error* -- :raises: *Invalid Dimensions Error* -- With description
With description
"""), """),
################################ ################################
(""" ("""
@@ -963,8 +933,7 @@ InvalidDimensionsError
""", """ """, """
Example Function Example Function
:raises: :exc:`InvalidDimensionsError` -- :raises: :exc:`InvalidDimensionsError` -- If the dimensions couldn't be parsed.
If the dimensions couldn't be parsed.
"""), """),
################################ ################################
(""" ("""
@@ -978,8 +947,7 @@ Invalid Dimensions Error
""", """ """, """
Example Function Example Function
:raises: *Invalid Dimensions Error* -- :raises: *Invalid Dimensions Error* -- If the dimensions couldn't be parsed.
If the dimensions couldn't be parsed.
"""), """),
################################ ################################
(""" ("""
@@ -1019,8 +987,8 @@ Raises
""", """ """, """
Example Function Example Function
:raises: :class:`exc.InvalidDimensionsError` -- :raises: :class:`exc.InvalidDimensionsError` -- If the dimensions couldn't """
If the dimensions couldn't be parsed. """be parsed.
"""), """),
################################ ################################
(""" ("""
@@ -1035,8 +1003,8 @@ Raises
""", """ """, """
Example Function Example Function
:raises: :class:`exc.InvalidDimensionsError` -- :raises: :class:`exc.InvalidDimensionsError` -- If the dimensions couldn't """
If the dimensions couldn't be parsed, """be parsed,
then a :class:`exc.InvalidDimensionsError` will be raised. then a :class:`exc.InvalidDimensionsError` will be raised.
"""), """),
################################ ################################
@@ -1053,10 +1021,10 @@ Raises
""", """ """, """
Example Function Example Function
:raises: * :class:`exc.InvalidDimensionsError` -- :raises: * :class:`exc.InvalidDimensionsError` -- If the dimensions """
If the dimensions couldn't be parsed. """couldn't be parsed.
* :class:`exc.InvalidArgumentsError` -- * :class:`exc.InvalidArgumentsError` -- If the arguments """
If the arguments are invalid. """are invalid.
"""), """),
################################ ################################
(""" ("""