Installation¶
This extension requires Python 3.5+, sphinx 1.6.5+ and is available from:
‘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 containimport matplotlib
orfrom 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
andYields
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
andspan.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 emptydict
.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 commonPython
standard library andNumPy
names for you. Then for your module, a usefuldict
may look like the following (e.g., if you were documentingsklearn.model_selection
):numpydoc_xref_aliases = { 'LeaveOneOut': 'sklearn.model_selection.LeaveOneOut', ... }
This option depends on the
numpydoc_xref_param_type
option beingTrue
.- 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.