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.

Advertisements

4 Responses

  1. Hi Yael, thanks for the great blog. Am I the only person that gets “ERROR: Unknown directive type “autosummary”” when following these steps?

    I think I’ve followed the instructions exactly. I’ve got a [question](http://stackoverflow.com/questions/20334804/sphinx-autodoc-and-numpydoc) about it on Stack Overflow. If an answer ever comes, it might be worth adding it to this blog post.

  2. You can also use napoleon (http://sphinxcontrib-napoleon.readthedocs.org/en/latest/), which supports both google-style and numpy-style docstrings out-of-the-box and works with python3 (which numpydoc did not in my experience).

    Also, it will be included in the upcoming Sphinx 1.3 so it seems to be the way to go.

  3. Reblogged this on GSOC 2016 and commented:
    Using Numpydoc instead of plain Sphinx.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: