Installation

This extension requires Python 3.5+, sphinx 1.6.5+ and is available from:

• numpydoc on PyPI

• numpydoc on GitHub

‘numpydoc’ should be added to the extensions option in your Sphinx conf.py. (Note that sphinx.ext.autosummary will automatically be loaded as well.)

Sphinx config options

The following options can be set in your Sphinx conf.py:

numpydoc_use_plotsbool

Whether to produce plot:: directives for Examples sections that contain import matplotlib or from matplotlib import.

numpydoc_show_class_membersbool

Whether to show all members of a class in the Methods and Attributes sections automatically. True by default.

numpydoc_show_inherited_class_membersbool

Whether to show all inherited members of a class in the Methods and Attributes sections automatically. If it’s false, inherited members won’t shown. True by default.

numpydoc_class_members_toctreebool

Whether to create a Sphinx table of contents for the lists of class methods and attributes. If a table of contents is made, Sphinx expects each entry to have a separate page. True by default.

numpydoc_citation_restr

A regular expression matching citations which should be mangled to avoid conflicts due to duplication across the documentation. Defaults to [\w-]+.

numpydoc_use_blockquotesbool

Until version 0.8, parameter definitions were shown as blockquotes, rather than in a definition list. If your styling requires blockquotes, switch this config option to True. This option will be removed in version 0.10.

numpydoc_attributes_as_param_listbool

Whether to format the Attributes section of a class page in the same way as the Parameter section. If it’s False, the Attributes section will be formatted as the Methods section using an autosummary table. True by default.

numpydoc_xref_param_typebool

Whether to create cross-references for the parameter types in the Parameters, Other Parameters, Returns and Yields sections of the docstring. False by default.

Note

Depending on the link types, the CSS styles might be different. consider overriding e.g. span.classifier a span.xref and span.classifier a code.docutils.literal.notranslate CSS classes to achieve a uniform appearance.

numpydoc_xref_aliasesdict

Mappings to fully qualified paths (or correct ReST references) for the aliases/shortcuts used when specifying the types of parameters. The keys should not have any spaces. Together with the intersphinx extension, you can map to links in any documentation. The default is an empty dict.

If you have the following intersphinx namespace configuration:

intersphinx_mapping = {
    'python': ('https://docs.python.org/3/', None),
    'numpy': ('https://docs.scipy.org/doc/numpy', None),
    ...
}

The default numpydoc_xref_aliases will supply some common Python standard library and NumPy names for you. Then for your module, a useful dict may look like the following (e.g., if you were documenting sklearn.model_selection):

numpydoc_xref_aliases = {
    'LeaveOneOut': 'sklearn.model_selection.LeaveOneOut',
    ...
}

This option depends on the numpydoc_xref_param_type option being True.

numpydoc_xref_ignoreset

Words not to cross-reference. Most likely, these are common words used in parameter type descriptions that may be confused for classes of the same name. For example:

numpydoc_xref_ignore = {'type', 'optional', 'default'}

The default is an empty set.

numpydoc_edit_linkbool

Deprecated since version edit: your HTML template instead

Whether to insert an edit link after docstrings.