How does NumPy process docstrings into sphinx documentation for Parameters?

Question

I want to build our documentation using sphinx and get the same formatting on parameters as the NumPy docs ( https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt )

I have found two ways to document parameters in this rst style with sphinx, one which is

:param name: description

or

:keyword name: description

and the other (which is the NumPy style)

Parameters
----------
name: type
    description

Here is an example of what that looks like:

http://docs.scipy.org/doc/numpy/reference/distutils.html#module-numpy.distutils

and the source

def get_subpackage(self,subpackage_name,
                   subpackage_path=None,
                   parent_name=None,
                   caller_level = 1):
    """Return list of subpackage configurations.

    Parameters
    ----------
    subpackage_name: str,None
        Name of the subpackage to get the configuration. '*' in
        subpackage_name is handled as a wildcard.
    subpackage_path: str
        If None, then the path is assumed to be the local path plus the
        subpackage_name. If a setup.py file is not found in the
        subpackage_path, then a default configuration is used.
    parent_name: str
        Parent name.
    """

However, when I build the docs with sphinx ( I am using sphinx-apidoc and sphinx-build ), I can generate the formatted lists when I use the first syntax ( :param name: description), but when I try to use the NumPy style I do not get the formatting. Looking at the rst syntax ( http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#sections ) it seems that something like

Parameters
----------

is just a section title. But using this formatting with sphinx the title Parameter does not appear in the output, and it gets none of the parameter section formatting.

Does anyone know how NumPy builds the documentation with sphinx to get this sort of formatting to work for parameters?

I have tried to look at the makefile and conf.py, and I'm just not sure how

Answer 1

NumPy uses a custom Sphinx extension: https://pypi.python.org/pypi/numpydoc.

You can install it with

pip install numpydoc

and then you add it to the sphinx conf.py file by adding to the extensions list

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