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_plots : bool

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

numpydoc_show_class_members : bool

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

numpydoc_show_inherited_class_members : bool

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_toctree : bool

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_re : str

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

numpydoc_use_blockquotes : bool

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_list : bool

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_type : bool

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_aliases : dict

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_ignore : set

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_link : bool

Deprecated since version edit: your HTML template instead

Whether to insert an edit link after docstrings.