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

Rendering of exceptions by napoleon. (#4046)

Browse Source 
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
2018-09-23 14:31:27 +02:00
committed by Rob Ruana
parent f5616139e8
commit dbb7c38220
2 changed files with 44 additions and 73 deletions
Download Patch File Download Diff File Expand all files Collapse all files

71
tests/test_ext_napoleon_docstring.py
View File

@@ -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()