sphinx.ext.napoleon.Config

Attributes

napoleon_google_docstring : bool (Defaults to True)

True to parse Google style docstrings. False to disable support for Google style docstrings.

napoleon_numpy_docstring : bool (Defaults to True)

True to parse NumPy style docstrings. False to disable support for NumPy style docstrings.

napoleon_include_init_with_doc : bool (Defaults to False)

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

napoleon_include_private_with_doc : bool (Defaults to False)

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

napoleon_include_special_with_doc : bool (Defaults to False)

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__)

napoleon_use_admonition_for_examples : bool (Defaults to False)

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

napoleon_use_admonition_for_notes : bool (Defaults to False)

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

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

napoleon_use_admonition_for_examples

napoleon_use_admonition_for_references : bool (Defaults to False)

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

napoleon_use_admonition_for_examples

napoleon_use_ivar : bool (Defaults to False)

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

napoleon_use_param : bool (Defaults to True)

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

napoleon_use_keyword : bool (Defaults to True)

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)

napoleon_use_param

napoleon_use_rtype : bool (Defaults to True)

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

napoleon_preprocess_types : bool (Defaults to False)

Enable the type preprocessor.

napoleon_type_aliases : dict (Defaults to None)

Add a mapping of strings to string, translating types in numpy style docstrings. Only works if napoleon_preprocess_types = True.

napoleon_custom_sections : list (Defaults to None)

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.
• To create a custom section that displays like the parameters or returns section, pass a tuple containing the custom section name and a string value, "params_style" or "returns_style".

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. If the second entry value is "params_style" or "returns_style", the custom section will be displayed like the parameters section or returns section.

napoleon_attr_annotations : bool (Defaults to True)

Use the type annotations of class attributes that are documented in the docstring but do not have a type in the docstring.