diff options
Diffstat (limited to 'doc/usage/extensions/napoleon.rst')
| -rw-r--r-- | doc/usage/extensions/napoleon.rst | 574 |
1 files changed, 574 insertions, 0 deletions
diff --git a/doc/usage/extensions/napoleon.rst b/doc/usage/extensions/napoleon.rst new file mode 100644 index 0000000..d2391da --- /dev/null +++ b/doc/usage/extensions/napoleon.rst @@ -0,0 +1,574 @@ +:mod:`sphinx.ext.napoleon` -- Support for NumPy and Google style docstrings +=========================================================================== + +.. module:: sphinx.ext.napoleon + :synopsis: Support for NumPy and Google style docstrings + +.. moduleauthor:: Rob Ruana + +.. versionadded:: 1.3 + +Overview +-------- + +.. highlight:: text + +Are you tired of writing docstrings that look like this:: + + :param path: The path of the file to wrap + :type path: str + :param field_storage: The :class:`FileStorage` instance to wrap + :type field_storage: FileStorage + :param temporary: Whether or not to delete the file when the File + instance is destructed + :type temporary: bool + :returns: A buffered writable file descriptor + :rtype: BufferedFileStorage + +`reStructuredText`_ is great, but it creates visually dense, hard to read +:pep:`docstrings <287>`. Compare the jumble above to the same thing rewritten +according to the `Google Python Style Guide`_:: + + Args: + path (str): The path of the file to wrap + field_storage (FileStorage): The :class:`FileStorage` instance to wrap + temporary (bool): Whether or not to delete the file when the File + instance is destructed + + Returns: + BufferedFileStorage: A buffered writable file descriptor + +Much more legible, no? + +Napoleon is a :term:`extension` that enables Sphinx to parse both `NumPy`_ and +`Google`_ style docstrings - the style recommended by `Khan Academy`_. + +Napoleon is a pre-processor that parses `NumPy`_ and `Google`_ style +docstrings and converts them to reStructuredText before Sphinx attempts to +parse them. This happens in an intermediate step while Sphinx is processing +the documentation, so it doesn't modify any of the docstrings in your actual +source code files. + +.. _ReStructuredText: https://docutils.sourceforge.io/rst.html +.. _Google Python Style Guide: + https://google.github.io/styleguide/pyguide.html +.. _Google: + https://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings +.. _NumPy: + https://numpydoc.readthedocs.io/en/latest/format.html#docstring-standard +.. _Khan Academy: + https://github.com/Khan/style-guides/blob/master/style/python.md#docstrings + +Getting Started +~~~~~~~~~~~~~~~ + +1. After :doc:`setting up Sphinx </usage/quickstart>` to build your docs, + enable napoleon in the Sphinx `conf.py` file:: + + # conf.py + + # Add napoleon to the extensions list + extensions = ['sphinx.ext.napoleon'] + +2. Use `sphinx-apidoc` to build your API documentation:: + + $ sphinx-apidoc -f -o docs/source projectdir + + +Docstrings +~~~~~~~~~~ + +Napoleon interprets every docstring that :mod:`autodoc <sphinx.ext.autodoc>` +can find, including docstrings on: ``modules``, ``classes``, ``attributes``, +``methods``, ``functions``, and ``variables``. Inside each docstring, +specially formatted `Sections`_ are parsed and converted to +reStructuredText. + +All standard reStructuredText formatting still works as expected. + + +.. _Sections: + +Docstring Sections +~~~~~~~~~~~~~~~~~~ + +All of the following section headers are supported: + +* ``Args`` *(alias of Parameters)* +* ``Arguments`` *(alias of Parameters)* +* ``Attention`` +* ``Attributes`` +* ``Caution`` +* ``Danger`` +* ``Error`` +* ``Example`` +* ``Examples`` +* ``Hint`` +* ``Important`` +* ``Keyword Args`` *(alias of Keyword Arguments)* +* ``Keyword Arguments`` +* ``Methods`` +* ``Note`` +* ``Notes`` +* ``Other Parameters`` +* ``Parameters`` +* ``Return`` *(alias of Returns)* +* ``Returns`` +* ``Raise`` *(alias of Raises)* +* ``Raises`` +* ``References`` +* ``See Also`` +* ``Tip`` +* ``Todo`` +* ``Warning`` +* ``Warnings`` *(alias of Warning)* +* ``Warn`` *(alias of Warns)* +* ``Warns`` +* ``Yield`` *(alias of Yields)* +* ``Yields`` + +Google vs NumPy +~~~~~~~~~~~~~~~ + +Napoleon supports two styles of docstrings: `Google`_ and `NumPy`_. The +main difference between the two styles is that Google uses indentation to +separate sections, whereas NumPy uses underlines. + +Google style: + +.. code-block:: python + + def func(arg1, arg2): + """Summary line. + + Extended description of function. + + Args: + arg1 (int): Description of arg1 + arg2 (str): Description of arg2 + + Returns: + bool: Description of return value + + """ + return True + +NumPy style: + +.. code-block:: python + + def func(arg1, arg2): + """Summary line. + + Extended description of function. + + Parameters + ---------- + arg1 : int + Description of arg1 + arg2 : str + Description of arg2 + + Returns + ------- + bool + Description of return value + + """ + return True + +NumPy style tends to require more vertical space, whereas Google style +tends to use more horizontal space. Google style tends to be easier to +read for short and simple docstrings, whereas NumPy style tends be easier +to read for long and in-depth docstrings. + +The choice between styles is largely aesthetic, but the two styles should +not be mixed. Choose one style for your project and be consistent with it. + +.. seealso:: + + For complete examples: + + * :ref:`example_google` + * :ref:`example_numpy` + + +Type Annotations +~~~~~~~~~~~~~~~~ + +:pep:`484` introduced a standard way to express types in Python code. +This is an alternative to expressing types directly in docstrings. +One benefit of expressing types according to :pep:`484` is that +type checkers and IDEs can take advantage of them for static code +analysis. :pep:`484` was then extended by :pep:`526` which introduced +a similar way to annotate variables (and attributes). + +Google style with Python 3 type annotations:: + + def func(arg1: int, arg2: str) -> bool: + """Summary line. + + Extended description of function. + + Args: + arg1: Description of arg1 + arg2: Description of arg2 + + Returns: + Description of return value + + """ + return True + + class Class: + """Summary line. + + Extended description of class + + Attributes: + attr1: Description of attr1 + attr2: Description of attr2 + """ + + attr1: int + attr2: str + +Google style with types in docstrings:: + + def func(arg1, arg2): + """Summary line. + + Extended description of function. + + Args: + arg1 (int): Description of arg1 + arg2 (str): Description of arg2 + + Returns: + bool: Description of return value + + """ + return True + + class Class: + """Summary line. + + Extended description of class + + Attributes: + attr1 (int): Description of attr1 + attr2 (str): Description of attr2 + """ + +.. Note:: + `Python 2/3 compatible annotations`_ aren't currently + supported by Sphinx and won't show up in the docs. + +.. _Python 2/3 compatible annotations: https://peps.python.org/pep-0484/#suggested-syntax-for-python-2-7-and-straddling-code + + +Configuration +------------- + +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 "sphinx.ext.napoleon" is enabled in `conf.py`:: + + # conf.py + + # Add any Sphinx extension module names here, as strings + extensions = ['sphinx.ext.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 = True + 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_preprocess_types = False + napoleon_type_aliases = None + napoleon_attr_annotations = True + +.. _Google style: + https://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings +.. _NumPy style: + https://numpydoc.readthedocs.io/en/latest/format.html#docstring-standard + +.. confval:: napoleon_google_docstring + + True to parse `Google style`_ docstrings. False to disable support + for Google style docstrings. *Defaults to True.* + +.. confval:: napoleon_numpy_docstring + + True to parse `NumPy style`_ docstrings. False to disable support + for NumPy style docstrings. *Defaults to True.* + +.. confval:: 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. *Defaults to False.* + + **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 + +.. confval:: 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. + *Defaults to False.* + + **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 + +.. confval:: 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. *Defaults to True.* + + **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__) + +.. confval:: 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. *Defaults to False.* + + 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 + +.. confval:: napoleon_use_admonition_for_notes + + True to use the ``.. admonition::`` directive for **Notes** sections. + False to use the ``.. rubric::`` directive instead. *Defaults to False.* + + .. note:: The singular **Note** section will always be converted to a + ``.. note::`` directive. + + .. seealso:: + + :confval:`napoleon_use_admonition_for_examples` + +.. confval:: napoleon_use_admonition_for_references + + True to use the ``.. admonition::`` directive for **References** + sections. False to use the ``.. rubric::`` directive instead. + *Defaults to False.* + + .. seealso:: + + :confval:`napoleon_use_admonition_for_examples` + +.. confval:: napoleon_use_ivar + + True to use the ``:ivar:`` role for instance variables. False to use + the ``.. attribute::`` directive instead. *Defaults to False.* + + 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 + +.. confval:: napoleon_use_param + + True to use a ``:param:`` role for each function parameter. False to + use a single ``:parameters:`` role for all the parameters. + *Defaults to True.* + + 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: :class:`int`, *optional* + + **If False**:: + + :parameters: * **arg1** (*str*) -- + Description of `arg1` + * **arg2** (*int, optional*) -- + Description of `arg2`, defaults to 0 + +.. confval:: 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. + *Defaults to True.* + + This behaves similarly to :confval:`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) + + .. seealso:: + + :confval:`napoleon_use_param` + +.. confval:: napoleon_use_rtype + + True to use the ``:rtype:`` role for the return type. False to output + the return type inline with the description. *Defaults to True.* + + 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 + +.. confval:: napoleon_preprocess_types + + True to convert the type definitions in the docstrings as references. + Defaults to *False*. + + .. versionadded:: 3.2.1 + .. versionchanged:: 3.5 + + Do preprocess the Google style docstrings also. + +.. confval:: napoleon_type_aliases + + A mapping to translate type names to other names or references. Works + only when ``napoleon_use_param = True``. *Defaults to None.* + + With:: + + napoleon_type_aliases = { + "CustomType": "mypackage.CustomType", + "dict-like": ":term:`dict-like <mapping>`", + } + + This `NumPy style`_ snippet:: + + Parameters + ---------- + arg1 : CustomType + Description of `arg1` + arg2 : dict-like + Description of `arg2` + + becomes:: + + :param arg1: Description of `arg1` + :type arg1: mypackage.CustomType + :param arg2: Description of `arg2` + :type arg2: :term:`dict-like <mapping>` + + .. versionadded:: 3.2 + +.. confval:: napoleon_attr_annotations + + True to allow using :pep:`526` attributes annotations in classes. + If an attribute is documented in the docstring without a type and + has an annotation in the class body, that type is used. + + .. versionadded:: 3.4 + +.. confval:: napoleon_custom_sections + + Add a list of custom sections to include, expanding the list of parsed sections. + *Defaults to None.* + + 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. + + .. versionadded:: 1.8 + .. versionchanged:: 3.5 + Support ``params_style`` and ``returns_style`` |