Getting started#

Installation#

This extension requires Python 3.7+, sphinx 3.0+ and is available from:

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

Configuration#

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 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 or "all"

How to handle terms not in numpydoc_xref_aliases when numpydoc_xref_aliases=True. The value can either be a set containing terms to ignore, or "all". In the former case, the set contains 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.

If the numpydoc_xref_ignore="all", then all unrecognized terms are ignored, i.e. terms not in numpydoc_xref_aliases are not wrapped in :obj: roles. This configuration parameter may be useful if you only want to create cross references for a small number of terms. In this case, including the desired cross reference mappings in numpydoc_xref_aliases and setting numpydoc_xref_ignore="all" is more convenient than explicitly listing terms to ignore in a set.

numpydoc_validation_checksset

The set of validation checks to report during the sphinx build process. The default is an empty set, so docstring validation is not run by default. If "all" is in the set, then the results of all of the built-in validation checks are reported. If the set includes "all" and additional error codes, then all validation checks except the listed error codes will be run. If the set contains only individual error codes, then only those checks will be run. For example:

# Report warnings for all validation checks
numpydoc_validation_checks = {"all"}

# Report warnings for all checks *except* for GL01, GL02, and GL05
numpydoc_validation_checks = {"all", "GL01", "GL02", "GL05"}

# Only report warnings for the SA01 and EX01 checks
numpydoc_validation_checks = {"SA01", "EX01"}

numpydoc_validation_excludeset

A container of strings using re syntax specifying patterns to ignore for docstring validation. For example, to skip docstring validation for all objects in mypkg.mymodule:

numpydoc_validation_exclude = {"mypkg.mymodule."}

If you wanted to also skip getter methods of MyClass:

numpydoc_validation_exclude = {r"mypkg\.mymodule\.", r"MyClass\.get$"}

The default is an empty set meaning no objects are excluded from docstring validation. Only has an effect when docstring validation is activated, i.e. numpydoc_validation_checks is not an empty set.