NumPyDoc vs. Sphinx and Google Format

Check out the differences between Sphinx and Google formats and NumPyDoc in Sphinx documentation built for html.

Sphinxy

format_exception.format_exception_Sphinx(etype, value, tb, limit=None)

Format the exception with a traceback.

Parameters:
  • etype (str) – exception type
  • value (int) – exception value
  • tb (traceback) – traceback object
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

Googley

I kind of hate the google format, even though the docstring is more human readable, the documented form is unspectacular.

format_exception.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)

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

NumPyDoc

On the other hand, I really like the NumPy format.

format_exception.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 [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).

Table Of Contents

Previous topic

Welcome to FoxyFormatException’s documentation!

Next topic

Consolidated Fields

This Page