mirror of
https://github.com/sphinx-doc/sphinx.git
synced 2025-02-25 18:55:22 -06:00
Rendering of exceptions by napoleon. (#4046)
This lets napoleon render exceptions using the standard info field syntax ``` :raises FooException: Some condition. ``` rather than the nonstandard ``` :raises: :exc:`FooException` -- Some condition. ``` Note that the previous approach was more forgiving if an explanatory text was given in the Raises section without an actual exception class: ``` Raises ------ If something occurs. ``` would be rendered as ``` :raises: *If something occurs* ``` which is OK-ish but is now rendered as ``` :raises If something occurs.: ``` which is somewhat more nonsensical. However neither the Google style guide nor numpydoc actually support this form (they always have both the type and the description) so I think the change is reasonable.
This commit is contained in:
Antony Lee
Rob Ruana
parent
f5616139e8
commit
dbb7c38220
@ -105,6 +105,10 @@ class GoogleDocstring(UnicodeMixin):
|
||||
<BLANKLINE>
|
||||
|
||||
"""
|
||||
|
||||
_name_rgx = re.compile(r"^\s*(:(?P<role>\w+):`(?P<name>[a-zA-Z0-9_.-]+)`|"
|
||||
r" (?P<name2>[a-zA-Z0-9_.-]+))\s*", re.X)
|
||||
|
||||
def __init__(self, docstring, config=None, app=None, what='', name='',
|
||||
obj=None, options=None):
|
||||
# type: (Union[unicode, List[unicode]], SphinxConfig, Sphinx, unicode, unicode, Any, Any) -> None # NOQA
|
||||
@ -697,39 +701,16 @@ class GoogleDocstring(UnicodeMixin):
|
||||
def _parse_raises_section(self, section):
|
||||
# type: (unicode) -> List[unicode]
|
||||
fields = self._consume_fields(parse_type=False, prefer_type=True)
|
||||
field_type = ':raises:'
|
||||
padding = ' ' * len(field_type)
|
||||
multi = len(fields) > 1
|
||||
lines = [] # type: List[unicode]
|
||||
for _name, _type, _desc in fields:
|
||||
for _, _type, _desc in fields:
|
||||
m = self._name_rgx.match(_type).groupdict()
|
||||
if m['role']:
|
||||
_type = m['name']
|
||||
_type = ' ' + _type if _type else ''
|
||||
_desc = self._strip_empty(_desc)
|
||||
has_desc = any(_desc)
|
||||
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, separator)
|
||||
elif has_desc and has_space:
|
||||
_type = '*%s*%s' % (_type, separator)
|
||||
else:
|
||||
_type = '%s%s' % (_type, separator)
|
||||
|
||||
if has_desc:
|
||||
field = [_type + _desc[0]] + _desc[1:]
|
||||
else:
|
||||
field = [_type]
|
||||
else:
|
||||
field = _desc
|
||||
if multi:
|
||||
if lines:
|
||||
lines.extend(self._format_block(padding + ' * ', field))
|
||||
else:
|
||||
lines.extend(self._format_block(field_type + ' * ', field))
|
||||
else:
|
||||
lines.extend(self._format_block(field_type + ' ', field))
|
||||
if lines and lines[-1]:
|
||||
_desc = ' ' + '\n '.join(_desc) if any(_desc) else ''
|
||||
lines.append(':raises%s:%s' % (_type, _desc))
|
||||
if lines:
|
||||
lines.append('')
|
||||
return lines
|
||||
|
||||
@ -976,9 +957,6 @@ class NumpyDocstring(GoogleDocstring):
|
||||
return True
|
||||
return False
|
||||
|
||||
_name_rgx = re.compile(r"^\s*(:(?P<role>\w+):`(?P<name>[a-zA-Z0-9_.-]+)`|"
|
||||
r" (?P<name2>[a-zA-Z0-9_.-]+))\s*", re.X)
|
||||
|
||||
def _parse_see_also_section(self, section):
|
||||
# type: (unicode) -> List[unicode]
|
||||
lines = self._consume_to_next_section()
|
||||
|
||||
@ -452,8 +452,8 @@ Raises:
|
||||
""", """
|
||||
Example Function
|
||||
|
||||
:raises: * :exc:`RuntimeError` -- A setting wasn't specified, or was invalid.
|
||||
* :exc:`ValueError` -- Something something value error.
|
||||
:raises RuntimeError: A setting wasn't specified, or was invalid.
|
||||
:raises ValueError: Something something value error.
|
||||
"""),
|
||||
################################
|
||||
("""
|
||||
@ -465,7 +465,7 @@ Raises:
|
||||
""", """
|
||||
Example Function
|
||||
|
||||
:raises: :exc:`InvalidDimensionsError`
|
||||
:raises InvalidDimensionsError:
|
||||
"""),
|
||||
################################
|
||||
("""
|
||||
@ -477,7 +477,7 @@ Raises:
|
||||
""", """
|
||||
Example Function
|
||||
|
||||
:raises: Invalid Dimensions Error
|
||||
:raises Invalid Dimensions Error:
|
||||
"""),
|
||||
################################
|
||||
("""
|
||||
@ -489,7 +489,7 @@ Raises:
|
||||
""", """
|
||||
Example Function
|
||||
|
||||
:raises: *Invalid Dimensions Error* -- With description
|
||||
:raises Invalid Dimensions Error: With description
|
||||
"""),
|
||||
################################
|
||||
("""
|
||||
@ -501,7 +501,7 @@ Raises:
|
||||
""", """
|
||||
Example Function
|
||||
|
||||
:raises: :exc:`InvalidDimensionsError` -- If the dimensions couldn't be parsed.
|
||||
:raises InvalidDimensionsError: If the dimensions couldn't be parsed.
|
||||
"""),
|
||||
################################
|
||||
("""
|
||||
@ -513,7 +513,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.
|
||||
"""),
|
||||
################################
|
||||
("""
|
||||
@ -525,7 +525,7 @@ Raises:
|
||||
""", """
|
||||
Example Function
|
||||
|
||||
:raises: If the dimensions couldn't be parsed.
|
||||
:raises If the dimensions couldn't be parsed.:
|
||||
"""),
|
||||
################################
|
||||
("""
|
||||
@ -537,7 +537,7 @@ Raises:
|
||||
""", """
|
||||
Example Function
|
||||
|
||||
:raises: :class:`exc.InvalidDimensionsError`
|
||||
:raises exc.InvalidDimensionsError:
|
||||
"""),
|
||||
################################
|
||||
("""
|
||||
@ -549,8 +549,7 @@ Raises:
|
||||
""", """
|
||||
Example Function
|
||||
|
||||
:raises: :class:`exc.InvalidDimensionsError` -- If the dimensions couldn't """
|
||||
"""be parsed.
|
||||
:raises exc.InvalidDimensionsError: If the dimensions couldn't be parsed.
|
||||
"""),
|
||||
################################
|
||||
("""
|
||||
@ -563,9 +562,8 @@ Raises:
|
||||
""", """
|
||||
Example Function
|
||||
|
||||
:raises: :class:`exc.InvalidDimensionsError` -- If the dimensions couldn't """
|
||||
"""be parsed,
|
||||
then a :class:`exc.InvalidDimensionsError` will be raised.
|
||||
:raises exc.InvalidDimensionsError: If the dimensions couldn't be parsed,
|
||||
then a :class:`exc.InvalidDimensionsError` will be raised.
|
||||
"""),
|
||||
################################
|
||||
("""
|
||||
@ -578,9 +576,8 @@ Raises:
|
||||
""", """
|
||||
Example Function
|
||||
|
||||
:raises: * :class:`exc.InvalidDimensionsError` -- If the dimensions """
|
||||
"""couldn't be parsed.
|
||||
* :class:`exc.InvalidArgumentsError` -- If the arguments are invalid.
|
||||
:raises exc.InvalidDimensionsError: If the dimensions couldn't be parsed.
|
||||
:raises exc.InvalidArgumentsError: If the arguments are invalid.
|
||||
"""),
|
||||
################################
|
||||
("""
|
||||
@ -593,8 +590,8 @@ Raises:
|
||||
""", """
|
||||
Example Function
|
||||
|
||||
:raises: * :class:`exc.InvalidDimensionsError`
|
||||
* :class:`exc.InvalidArgumentsError`
|
||||
:raises exc.InvalidDimensionsError:
|
||||
:raises exc.InvalidArgumentsError:
|
||||
""")]
|
||||
for docstring, expected in docstrings:
|
||||
actual = str(GoogleDocstring(docstring))
|
||||
@ -1346,8 +1343,8 @@ Raises
|
||||
""", """
|
||||
Example Function
|
||||
|
||||
:raises: * :exc:`RuntimeError` -- A setting wasn't specified, or was invalid.
|
||||
* :exc:`ValueError` -- Something something value error.
|
||||
:raises RuntimeError: A setting wasn't specified, or was invalid.
|
||||
:raises ValueError: Something something value error.
|
||||
"""),
|
||||
################################
|
||||
("""
|
||||
@ -1360,7 +1357,7 @@ InvalidDimensionsError
|
||||
""", """
|
||||
Example Function
|
||||
|
||||
:raises: :exc:`InvalidDimensionsError`
|
||||
:raises InvalidDimensionsError:
|
||||
"""),
|
||||
################################
|
||||
("""
|
||||
@ -1373,7 +1370,7 @@ Invalid Dimensions Error
|
||||
""", """
|
||||
Example Function
|
||||
|
||||
:raises: Invalid Dimensions Error
|
||||
:raises Invalid Dimensions Error:
|
||||
"""),
|
||||
################################
|
||||
("""
|
||||
@ -1387,7 +1384,7 @@ Invalid Dimensions Error
|
||||
""", """
|
||||
Example Function
|
||||
|
||||
:raises: *Invalid Dimensions Error* -- With description
|
||||
:raises Invalid Dimensions Error: With description
|
||||
"""),
|
||||
################################
|
||||
("""
|
||||
@ -1401,7 +1398,7 @@ InvalidDimensionsError
|
||||
""", """
|
||||
Example Function
|
||||
|
||||
:raises: :exc:`InvalidDimensionsError` -- If the dimensions couldn't be parsed.
|
||||
:raises InvalidDimensionsError: If the dimensions couldn't be parsed.
|
||||
"""),
|
||||
################################
|
||||
("""
|
||||
@ -1415,7 +1412,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.
|
||||
"""),
|
||||
################################
|
||||
("""
|
||||
@ -1428,7 +1425,7 @@ If the dimensions couldn't be parsed.
|
||||
""", """
|
||||
Example Function
|
||||
|
||||
:raises: If the dimensions couldn't be parsed.
|
||||
:raises If the dimensions couldn't be parsed.:
|
||||
"""),
|
||||
################################
|
||||
("""
|
||||
@ -1441,7 +1438,7 @@ Raises
|
||||
""", """
|
||||
Example Function
|
||||
|
||||
:raises: :class:`exc.InvalidDimensionsError`
|
||||
:raises exc.InvalidDimensionsError:
|
||||
"""),
|
||||
################################
|
||||
("""
|
||||
@ -1455,8 +1452,7 @@ Raises
|
||||
""", """
|
||||
Example Function
|
||||
|
||||
:raises: :class:`exc.InvalidDimensionsError` -- If the dimensions couldn't """
|
||||
"""be parsed.
|
||||
:raises exc.InvalidDimensionsError: If the dimensions couldn't be parsed.
|
||||
"""),
|
||||
################################
|
||||
("""
|
||||
@ -1471,9 +1467,8 @@ Raises
|
||||
""", """
|
||||
Example Function
|
||||
|
||||
:raises: :class:`exc.InvalidDimensionsError` -- If the dimensions couldn't """
|
||||
"""be parsed,
|
||||
then a :class:`exc.InvalidDimensionsError` will be raised.
|
||||
:raises exc.InvalidDimensionsError: If the dimensions couldn't be parsed,
|
||||
then a :class:`exc.InvalidDimensionsError` will be raised.
|
||||
"""),
|
||||
################################
|
||||
("""
|
||||
@ -1489,10 +1484,8 @@ Raises
|
||||
""", """
|
||||
Example Function
|
||||
|
||||
:raises: * :class:`exc.InvalidDimensionsError` -- If the dimensions """
|
||||
"""couldn't be parsed.
|
||||
* :class:`exc.InvalidArgumentsError` -- If the arguments """
|
||||
"""are invalid.
|
||||
:raises exc.InvalidDimensionsError: If the dimensions couldn't be parsed.
|
||||
:raises exc.InvalidArgumentsError: If the arguments are invalid.
|
||||
"""),
|
||||
################################
|
||||
("""
|
||||
@ -1506,8 +1499,8 @@ Raises
|
||||
""", """
|
||||
Example Function
|
||||
|
||||
:raises: * :class:`exc.InvalidDimensionsError`
|
||||
* :class:`exc.InvalidArgumentsError`
|
||||
:raises exc.InvalidDimensionsError:
|
||||
:raises exc.InvalidArgumentsError:
|
||||
""")]
|
||||
for docstring, expected in docstrings:
|
||||
config = Config()
|
||||
|
||||
Loading…
Reference in New Issue
Block a user