sphinxcontrib.napoleon¶

Support for NumPy and Google style docstrings.

classsphinxcontrib.napoleon.Config(**settings)[source]¶

Sphinx napoleon extension settings inconf.py.

Listed below are all the settings used by napoleon and their defaultvalues. These settings can be changed in the Sphinxconf.py file. Makesure that “sphinxcontrib.napoleon” is enabled inconf.py:

# conf.py# Add any Sphinx extension module names here, as stringsextensions=['sphinxcontrib.napoleon']# Napoleon settingsnapoleon_google_docstring=Truenapoleon_numpy_docstring=Truenapoleon_include_init_with_doc=Falsenapoleon_include_private_with_doc=Falsenapoleon_include_special_with_doc=Falsenapoleon_use_admonition_for_examples=Falsenapoleon_use_admonition_for_notes=Falsenapoleon_use_admonition_for_references=Falsenapoleon_use_ivar=Falsenapoleon_use_param=Truenapoleon_use_rtype=Truenapoleon_use_keyword=Truenapoleon_custom_sections=None

napoleon_google_docstring¶

True to parseGoogle style docstrings. False to disable supportfor Google style docstrings.

Type:	bool (Defaults to True)

napoleon_numpy_docstring¶

True to parseNumPy style docstrings. False to disable supportfor NumPy style docstrings.

Type:	bool (Defaults to True)

napoleon_include_init_with_doc¶

True to list__init___ docstrings separately from the classdocstring. False to fall back to Sphinx’s default behavior, whichconsiders the__init___ docstring as part of the classdocumentation.

If True:

def__init__(self):"""    This will be included in the docs because it has a docstring    """def__init__(self):# This will NOT be included in the docs

Type:	bool (Defaults to False)

napoleon_include_private_with_doc¶

True to include private members (like_membername) with docstringsin the documentation. False to fall back to Sphinx’s default behavior.

If True:

def_included(self):"""    This will be included in the docs because it has a docstring    """passdef_skipped(self):# This will NOT be included in the docspass

Type:	bool (Defaults to False)

napoleon_include_special_with_doc¶

True to include special members (like__membername__) withdocstrings in the documentation. False to fall back to Sphinx’sdefault behavior.

If True:

def__str__(self):"""    This will be included in the docs because it has a docstring    """returnunicode(self).encode('utf-8')def__unicode__(self):# This will NOT be included in the docsreturnunicode(self.__class__.__name__)

Type:	bool (Defaults to False)

napoleon_use_admonition_for_examples¶

True to use the..admonition:: directive for theExample andExamples sections. False to use the..rubric:: directiveinstead. One may look better than the other depending on what HTMLtheme is used.

ThisNumPy style snippet will be converted as follows:

Example-------Thisisjustaquickexample

If True:

..admonition::ExampleThisisjustaquickexample

If False:

..rubric::ExampleThisisjustaquickexample

Type:	bool (Defaults to False)

napoleon_use_admonition_for_notes¶

True to use the..admonition:: directive forNotes sections.False to use the..rubric:: directive instead.

Note

The singularNote section will always be converted to a..note:: directive.

See also

napoleon_use_admonition_for_examples

Type:	bool (Defaults to False)

napoleon_use_admonition_for_references¶

True to use the..admonition:: directive forReferencessections. False to use the..rubric:: directive instead.

See also

napoleon_use_admonition_for_examples

Type:	bool (Defaults to False)

napoleon_use_ivar¶

True to use the:ivar: role for instance variables. False to usethe..attribute:: directive instead.

ThisNumPy style snippet will be converted as follows:

Attributes----------attr1 : int    Description of `attr1`

If True:

:ivar attr1: Description of `attr1`:vartype attr1: int

If False:

.. attribute:: attr1   Description of `attr1`   :type: int

Type:	bool (Defaults to False)

napoleon_use_param¶

True to use a:param: role for each function parameter. False touse a single:parameters: role for all the parameters.

ThisNumPy style snippet will be converted as follows:

Parameters----------arg1 : str    Description of `arg1`arg2 : int, optional    Description of `arg2`, defaults to 0

If True:

:param arg1: Description of `arg1`:type arg1: str:param arg2: Description of `arg2`, defaults to 0:type arg2: int, optional

If False:

:parameters: * **arg1** (*str*) --               Description of `arg1`             * **arg2** (*int, optional*) --               Description of `arg2`, defaults to 0

Type:	bool (Defaults to True)

napoleon_use_keyword¶

True to use a:keyword: role for each function keyword argument.False to use a single:keywordarguments: role for all thekeywords.

This behaves similarly tonapoleon_use_param. Note unlikedocutils,:keyword: and:param: will not be treated the sameway - there will be a separate “Keyword Arguments” section, renderedin the same fashion as “Parameters” section (type links created ifpossible)

See also

napoleon_use_param

Type:	bool (Defaults to True)

napoleon_use_rtype¶

True to use the:rtype: role for the return type. False to outputthe return type inline with the description.

ThisNumPy style snippet will be converted as follows:

Returns-------boolTrueifsuccessful,Falseotherwise

If True:

:returns:Trueifsuccessful,Falseotherwise:rtype:bool

If False:

:returns:*bool*--Trueifsuccessful,Falseotherwise

Type:	bool (Defaults to True)

napoleon_custom_sections¶

Add a list of custom sections to include, expanding the list of parsed sections.

The entries can either be strings or tuples, depending on the intention:

• To create a custom “generic” section, just pass a string.
• To create an alias for an existing section, pass a tuple containing thealias name and the original, in that order.

If an entry is just a string, it is interpreted as a header for a genericsection. If the entry is a tuple/list/indexed container, the first entryis the name of the section, the second is the section key to emulate.

Type:	list (Defaults to None)

sphinxcontrib.napoleon.setup(app)[source]¶

Sphinx extension setup function.

When the extension is loaded, Sphinx imports this module and executesthesetup() function, which in turn notifies Sphinx of everythingthe extension offers.

Parameters:	app (sphinx.application.Sphinx) – Application object representing the Sphinx process

See also

The Sphinx documentation on Extensions

The Extension Tutorial

The Extension API

sphinxcontrib.napoleon.docstring module¶