Docstrings¶

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

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

… for function-like objects:

.. autofunction::¶
.. automethod::¶
.. autoproperty::¶
.. autodecorator::¶

… for data and attributes:

.. autodata::¶
.. autoattribute::¶

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.

Guidelines¶

In PEP 8 there is only a brief reference to conventions for a good docstring: Documentation Strings. Other PEPs refer to the Docstring Processing System Framework:

PEP 257

describes docstring conventions:

What should be documented where?
The first line should be a one-line summary.

PEP 258

specifies the docstring processing system.

PEP 287

specifies the docstring syntax.

The Google Python Style Guide also provides more specific guidelines for RPython comments and docstrings. The NumPy style guide also provides further docstring standards. The main difference between the two is that Google uses indentation and NumPy uses underlining:

Google Python Style Guide:

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 Guide:

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

`sphinx.ext.napoleon`¶

The Sphinx extension sphinx.ext.napoleon processes docstrings that correspond to both the Google Python Style Guide and the NumPy Style Guide:

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

`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 in Docstrings:

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