Adding Numpydoc to Sphinx

This post is a continuation to the Sphinx Autodoc Tutorial for Dummies.

Sphinx has great documentation, but sometimes its documentation requirements can be somewhat awkward when looking at the code.

Here is a Sphinx function documentation example, which looks like this:

def public_fn_with_sphinxy_docstring(name, state=None):
    """This function does something.

    :param name: The name to use.
    :type name: str.
    :param state: Current state to be in.
    :type state: bool.
    :returns:  int -- the return code.
    :raises: AttributeError, KeyError

    """

Not that intuitive, IMHO.

Numpy is an excellent Python package for scientific computing, and they also offer their own Sphinx extension for documentation, numpydoc, that 1) looks good in html, and 2) looks clear in code.

Here is a Numpydoc function documentation example, which looks like this:

def foo(var1, var2, long_var_name='hi')
    """This function does something.

    Parameters
    ----------
    var1 : array_like
        This is a type.
    var2 : int
        This is another var.
    Long_variable_name : {'hi', 'ho'}, optional
        Choices in brackets, default first when optional.

    Returns
    -------
    describe : type
        Explanation
    """

I personally find the numpy version quite a bit more intuitive, and it looks great.

Installation

Super simple (easy_install reference).

easy_install numpydoc

And then add

extensions = ['numpydoc']

to your conf.py file. If you’re already using autodoc or other extensions, the line will look like this:

extensions = ['sphinx.ext.autodoc', 'numpydoc']

That’s it! Running

make html

should compile your documentation using numpydoc. If you don’t care for it – no problem – just remove the extension from conf.py.