Check out the differences between Sphinx and Google formats and NumPyDoc in Sphinx documentation built for html.
Format the exception with a traceback.
| Parameters: |
|
|---|---|
| Key limit: | maximum number of stack frames to show [optional] |
| Returns: | out |
| Return type: | list of strings |
| Raises : | AttributeError, KeyError |
A really great idea. A way you might use me is
>>> data = format_exception_Sphinx('stoopid', 1, ValueError)
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
:key 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 kind of hate the google format, even though the docstring is more human readable, the documented form is unspectacular.
Format the exception with a traceback.
etype (str): exception type
value (int): exception value
tb (traceback): traceback object
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
Kwargs:
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 : | etype : str
value : int
tb : traceback
limit : int or None
|
|---|---|
| Returns : | out : list of strings
|
See also
Notes
This is an example of autodoc using numpydoc, the Numpy documentation format with the numpydoc extension [R1]
This explanation of the column headers is not complete, for an exhaustive specification see [R2].
References
| [R1] | (1, 2) numpydoc, Numpy Documentation. |
| [R2] | (1, 2) 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).