Python Docstring Formatting

Docstring Flavors

Python uses docstrings to document code. A docstring is a string that is the first statement in a package, module, class or function. Python docstrings are written in the reStructuredText syntax (abbreviated as RST or reST).

There are at least 4 flavors of docstrings, each following the PEP 257 conventions. The following examples show how to document a function parameter:

Epytext:

@type param1: int
@param param1: The first parameter

Sphinx:

:param param1: The first parameter
:type: int

Google:

Args:
    param1 (int): The first parameter

NumPy:

Parameters
----------
param1 : int
    The first parameter

DSP-TOOLS uses the Google style without typing, as defined here.

Existing Formatters

pydocstyle

Static analysis tool for checking compliance with Python docstring conventions. Pydocstyle supports most PEP 257 conventions out of the box, but it should not be considered a reference implementation. Pydocstyle seems to be the most popular docstring checker. It supports the styles "pep257", "numpy", and "google".

pydocstringformatter

A docstring formatter that follows PEP 8 and PEP 257 but makes some of the more controversial elements of those PEPs optional. Can be configured for other styles as well. This project is heavily inspired by docformatter. Supported styles: "pep257", "numpy".

docformatter

Automatically formats docstrings to follow a subset of the PEP 257 conventions. Currently, only the style "sphinx" and "epytext" are recognized, but "numpy" and "google" are future styles.

darglint

Docstring linter which checks whether a docstring's description matches the actual function/method implementation. Supports the styles "sphinx", "google", and "numpy".