How can I produce a numpy-like documentation?

Question

I'm working a lot with spyder and the object inspector, which I find pretty convenient as an instant help function. Some modules seem to profit very nicely from this function. For example a pretty basic numpy function (numpy.absolute) produces the following view in the object inspector:

I want to know, how I can write my own modules in such a way, that such a nice view is produced when I call my functions in spyder.

Answer 1

For your documentation to render as nicely as the numpy one, you need to follow the NumpyDoc standard. Suppose you have a function called func with two arguments like this:

def func(arg1, arg2):
    return True

To add documentation to it you need to write a multiline string below its definition (called in the Python world docstring), like this

def func(arg1, arg2):
    """Summary line.

    Extended description of function.

    Parameters
    ----------
    arg1 : int
        Description of arg1
    arg2 : str
        Description of arg2

    Returns
    -------
    bool
        Description of return value

    Examples
    --------
    >>> func(1, "a")
    True
    """
    return True

What Spyder does is that it takes this plain text description, parses and renders it as html and finally shows it in the Object Inspector.

To see it you just need to call func somewhere else in your code and press Ctrl+i next to it, like this:

func<Ctrl+i>(1, "a")

This is also shown automatically when you write a left parenthesis next to func.

Answer 2

If you have your Python project (or file) already documented with an other style (as reStructuredText or Epytext) or not documented, you can generate/convert the docstrings into NumpyDoc style using Pyment:

pyment -o numpydoc /my/python/project

Note that the previous command, run after installed Pyment, will generate patches that should be applied to your code.

Once your project is documented using Numpydoc style, you can use the Sphinx extension to generate your nice readable NumpyDoc style documentation!