sphinxcontrib.napoleon package¶
sphinxcontrib.napoleon¶
Support for NumPy and Google style docstrings.
copyright: | Copyright 2013-2018 by Rob Ruana, see AUTHORS. |
---|---|
license: | BSD, see LICENSE for details. |
-
class
sphinxcontrib.napoleon.
Config
(**settings)[source]¶ Sphinx napoleon extension settings in conf.py.
Listed below are all the settings used by napoleon and their default values. These settings can be changed in the Sphinx conf.py file. Make sure that “sphinxcontrib.napoleon” is enabled in conf.py:
# conf.py # Add any Sphinx extension module names here, as strings extensions = ['sphinxcontrib.napoleon'] # Napoleon settings napoleon_google_docstring = True napoleon_numpy_docstring = True napoleon_include_init_with_doc = False napoleon_include_private_with_doc = False napoleon_include_special_with_doc = False napoleon_use_admonition_for_examples = False napoleon_use_admonition_for_notes = False napoleon_use_admonition_for_references = False napoleon_use_ivar = False napoleon_use_param = True napoleon_use_rtype = True napoleon_use_keyword = True napoleon_custom_sections = None
-
napoleon_google_docstring
¶ True to parse Google style docstrings. False to disable support for Google style docstrings.
Type: bool
(Defaults to True)
-
napoleon_numpy_docstring
¶ True to parse NumPy style docstrings. False to disable support for NumPy style docstrings.
Type: bool
(Defaults to True)
-
napoleon_include_init_with_doc
¶ True to list
__init___
docstrings separately from the class docstring. False to fall back to Sphinx’s default behavior, which considers the__init___
docstring as part of the class documentation.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 docstrings in 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 """ pass def _skipped(self): # This will NOT be included in the docs pass
Type: bool
(Defaults to False)
-
napoleon_include_special_with_doc
¶ True to include special members (like
__membername__
) with docstrings in the documentation. False to fall back to Sphinx’s default behavior.If True:
def __str__(self): """ This will be included in the docs because it has a docstring """ return unicode(self).encode('utf-8') def __unicode__(self): # This will NOT be included in the docs return unicode(self.__class__.__name__)
Type: bool
(Defaults to False)
-
napoleon_use_admonition_for_examples
¶ True to use the
.. admonition::
directive for the Example and Examples sections. False to use the.. rubric::
directive instead. One may look better than the other depending on what HTML theme is used.This NumPy style snippet will be converted as follows:
Example ------- This is just a quick example
If True:
.. admonition:: Example This is just a quick example
If False:
.. rubric:: Example This is just a quick example
Type: bool
(Defaults to False)
-
napoleon_use_admonition_for_notes
¶ True to use the
.. admonition::
directive for Notes sections. False to use the.. rubric::
directive instead.Note
The singular Note section will always be converted to a
.. note::
directive.See also
Type: bool
(Defaults to False)
-
napoleon_use_admonition_for_references
¶ True to use the
.. admonition::
directive for References sections. False to use the.. rubric::
directive instead.See also
Type: bool
(Defaults to False)
-
napoleon_use_ivar
¶ True to use the
:ivar:
role for instance variables. False to use the.. attribute::
directive instead.This NumPy 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 to use a single:parameters:
role for all the parameters.This NumPy 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:keyword arguments:
role for all the keywords.This behaves similarly to
napoleon_use_param
. Note unlike docutils,:keyword:
and:param:
will not be treated the same way - there will be a separate “Keyword Arguments” section, rendered in the same fashion as “Parameters” section (type links created if possible)See also
Type: bool
(Defaults to True)
-
napoleon_use_rtype
¶ True to use the
:rtype:
role for the return type. False to output the return type inline with the description.This NumPy style snippet will be converted as follows:
Returns ------- bool True if successful, False otherwise
If True:
:returns: True if successful, False otherwise :rtype: bool
If False:
:returns: *bool* -- True if successful, False otherwise
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 the alias name and the original, in that order.
If an entry is just a string, it is interpreted as a header for a generic section. If the entry is a tuple/list/indexed container, the first entry is 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 executes the
setup()
function, which in turn notifies Sphinx of everything the extension offers.Parameters: app (sphinx.application.Sphinx) – Application object representing the Sphinx process
sphinxcontrib.napoleon.docstring module¶
sphinxcontrib.napoleon.docstring¶
Classes for docstring parsing and formatting.
copyright: | Copyright 2013-2018 by Rob Ruana, see AUTHORS. |
---|---|
license: | BSD, see LICENSE for details. |
-
class
sphinxcontrib.napoleon.docstring.
GoogleDocstring
(docstring, config=None, app=None, what='', name='', obj=None, options=None)[source]¶ Bases:
pockets.string.UnicodeMixin
Convert Google style docstrings to reStructuredText.
Parameters: - docstring (
str
orlist
ofstr
) – The docstring to parse, given either as a string or split into individual lines. - config (
sphinxcontrib.napoleon.Config
orsphinx.config.Config
) – The configuration settings to use. If not given, defaults to the config object on app; or if app is not given defaults to the a newsphinxcontrib.napoleon.Config
object.
Other Parameters: - app (
sphinx.application.Sphinx
, optional) – Application object representing the Sphinx process. - what (
str
, optional) – A string specifying the type of the object to which the docstring belongs. Valid values: “module”, “class”, “exception”, “function”, “method”, “attribute”. - name (
str
, optional) – The fully qualified name of the object. - obj (module, class, exception, function, method, or attribute) – The object to which the docstring belongs.
- options (
sphinx.ext.autodoc.Options
, optional) – The options given to the directive: an object with attributes inherited_members, undoc_members, show_inheritance and noindex that are True if the flag option of same name was given to the auto directive.
Example
>>> from sphinxcontrib.napoleon import Config >>> config = Config(napoleon_use_param=True, napoleon_use_rtype=True) >>> docstring = '''One line summary. ... ... Extended description. ... ... Args: ... arg1(int): Description of `arg1` ... arg2(str): Description of `arg2` ... Returns: ... str: Description of return value. ... ''' >>> print(GoogleDocstring(docstring, config)) One line summary. <BLANKLINE> Extended description. <BLANKLINE> :param arg1: Description of `arg1` :type arg1: int :param arg2: Description of `arg2` :type arg2: str <BLANKLINE> :returns: Description of return value. :rtype: str <BLANKLINE>
- docstring (
-
class
sphinxcontrib.napoleon.docstring.
NumpyDocstring
(docstring, config=None, app=None, what='', name='', obj=None, options=None)[source]¶ Bases:
sphinxcontrib.napoleon.docstring.GoogleDocstring
Convert NumPy style docstrings to reStructuredText.
Parameters: - docstring (
str
orlist
ofstr
) – The docstring to parse, given either as a string or split into individual lines. - config (
sphinxcontrib.napoleon.Config
orsphinx.config.Config
) – The configuration settings to use. If not given, defaults to the config object on app; or if app is not given defaults to the a newsphinxcontrib.napoleon.Config
object.
Other Parameters: - app (
sphinx.application.Sphinx
, optional) – Application object representing the Sphinx process. - what (
str
, optional) – A string specifying the type of the object to which the docstring belongs. Valid values: “module”, “class”, “exception”, “function”, “method”, “attribute”. - name (
str
, optional) – The fully qualified name of the object. - obj (module, class, exception, function, method, or attribute) – The object to which the docstring belongs.
- options (
sphinx.ext.autodoc.Options
, optional) – The options given to the directive: an object with attributes inherited_members, undoc_members, show_inheritance and noindex that are True if the flag option of same name was given to the auto directive.
Example
>>> from sphinxcontrib.napoleon import Config >>> config = Config(napoleon_use_param=True, napoleon_use_rtype=True) >>> docstring = '''One line summary. ... ... Extended description. ... ... Parameters ... ---------- ... arg1 : int ... Description of `arg1` ... arg2 : str ... Description of `arg2` ... Returns ... ------- ... str ... Description of return value. ... ''' >>> print(NumpyDocstring(docstring, config)) One line summary. <BLANKLINE> Extended description. <BLANKLINE> :param arg1: Description of `arg1` :type arg1: int :param arg2: Description of `arg2` :type arg2: str <BLANKLINE> :returns: Description of return value. :rtype: str <BLANKLINE>
-
__str__
()¶ Return the parsed docstring in reStructuredText format.
Returns: UTF-8 encoded version of the docstring. Return type: str
-
__unicode__
()¶ Return the parsed docstring in reStructuredText format.
Returns: Unicode version of the docstring. Return type: unicode
- docstring (