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".