Docstrings

With the Sphinx extension sphinx.ext.autodoc, docstrings can also be included in the documentation. The following three directives can be specified:

.. automodule::
.. autoclass::
.. autoexception::

These document a module, a class or an exception using the docstring of the respective object.

Installation

sphinx.ext.autodoc is usually already specified in the Sphinx configuration file docs/conf.py:

extensions = ["sphinx.ext.autodoc", ...]

If your package and its documentation are part of the same repository, they will always have the same relative position in the filesystem. In this case you can simply edit the Sphinx configuration for sys.path to indicate the relative path to the package, so:

sys.path.insert(0, os.path.abspath(".."))
import requests

If you have installed your Sphinx documentation in a virtual environment, you can also install your package there with:

$ python -m pip install my.package

or, if you want to develop the package further with:

$ python -m pip install -e https://github.com/veit/my.package.git

Examples

Here you can find some examples from the documentation of the Python string module:

``autodoc`` example
===================

``string`` module
-----------------

.. automodule:: string

``string.Template`` class
-------------------------

.. autoclass:: Template

``string.capwords`` function
----------------------------

.. autofunction:: capwords

This leads to the autodoc example.

Note

You should follow these guidelines when writing docstrings:

sphinx-autodoc-typehints

With PEP 484 a standard method for expressing types in Python code was introduced. This also allows types to be expressed differently in docstrings. The variant with types according to PEP 484 has the advantage that type testers and IDEs can be used for static code analysis.

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

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

Note

PEP 484#suggested-syntax-for-python-2-7-and-straddling-code are currently

not supported by Sphinx and do not appear in the generated documentation.

sphinx.ext.napoleon

The sphinx extension sphinx.ext.napoleon allows you to define different sections in docstrings, including:

  • Attributes

  • Example

  • Keyword Arguments

  • Methods

  • Parameters

  • Warning

  • Yield

There are two styles of docstrings in sphinx.ext.napoleon:

The main differences are that Google uses indentations and NumPy uses underscores:

Google:

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:

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

You can find the detailed configuration options in sphinxcontrib.napoleon.Config.