Check out the differences between Sphinx and Google formats and NumPyDoc in Sphinx documentation built for html.
Format the exception with a traceback.
| Parameters: |
|
|---|---|
| Returns: | out |
| Return type: | list of strings |
| Raises: | AttributeError, KeyError |
See also
numpy: a numerical packge
Note
This is an example of Sphinxy [1] format.
A really great idea. A way you might use me is
>>> data = format_exception_Sphinx('stoopid', 1, ValueError)
Footnotes
| [1] | sphinx |
That’s based on this docstring from an example in the Sphinx tutorial which I embellished slightly:
def format_exception_Sphinx(etype, value, tb, limit=None):
"""
Format the exception with a traceback.
:arg etype: exception type
:type etype: str
:arg value: exception value
:type value: int
:arg tb: traceback object
:type tb: traceback
:keyword limit: maximum number of stack frames to show [optional]
:type limit: int or None
:returns: out
:rtype: list of strings
:raises: AttributeError, KeyError
A really great idea. A way you might use me is
>>> data = format_exception_Sphinx('stoopid', 1, ValueError)
"""
return etype, value, tb
I used to hate the Google-style format, even though the docstring is more human readable, the documented form was unspectacular. But now with Napoleon it’s the same as the sphinx format.
Format the exception with a traceback.
| Parameters: |
|
|---|---|
| Keyword Arguments: | |
limit (int or None) – maximum number of stack frames to show [optional] |
|
| Returns: | out – list of strings |
| Raises: | AttributeError, KeyError – |
A really great idea. A way you might use me is
>>> data = format_exception_google('wow', 999, KeyError)
Here’s the recommended Google format:
def format_exception_google(etype, value, tb, limit=None):
"""
Format the exception with a traceback.
Args:
etype (str): exception type
value (int): exception value
tb (traceback): traceback object
Keyword Args:
limit (int or None): maximum number of stack frames to show [optional]
Returns:
out: list of strings
Raises:
AttributeError, KeyError
A really great idea. A way you might use me is
>>> data = format_exception_google('wow', 999, KeyError)
"""
return etype, value, tb
On the other hand, I really like the NumPy format.
Format the exception with a traceback.
| Parameters: |
|
|---|---|
| Returns: | out (list of strings) – list of strings |
| Raises: | AttributeError, KeyError – |
See also
numpy : a numerical package
Notes
This is an example of autodoc using numpydoc, the Numpy documentation format with the numpydoc extension [2]
This explanation of the column headers is not complete, for an exhaustive specification see [3].
References
| [2] | numpydoc, Numpy Documentation. |
| [3] | Sphinx, Sphinx Domains Documentation. |
Examples
>>> data = format_exception_numpy('dumb', 0, IOError)
The docstring for NumPyDoc is very readable:
def format_exception_numpy(etype, value, tb, limit=None):
"""
Format the exception with a traceback.
Parameters
----------
etype : str
exception type
value : int
exception value
tb : traceback
traceback object
limit : int or None
maximum number of stack frames to show
Returns
-------
out : list of strings
list of strings
See Also
--------
numpy : a numerical package
Notes
-----
This is an example of autodoc using numpydoc, the Numpy documentation format
with the numpydoc extension [1]_
This explanation of the column headers is not complete, for an exhaustive
specification see [2]_.
References
----------
.. [1] `numpydoc <https://github.com/numpy/numpy/tree/master/doc/sphinxext>`_, \
Numpy Documentation.
.. [2] `Sphinx <http://sphinx-doc.org/domains.html#domains>`_, Sphinx Domains \
Documentation.
Examples
--------
>>> data = format_exception_numpy('dumb', 0, IOError)
"""
return etype, value, tb
Haven’t tried to use np in rst docs, only as autodoc from .py docstrings. It does include directives for “numpy” domain as “np”. Unfortunately Numpydoc also makes 2 sets of module indices, (py-modules and np-modules).