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 docsrings 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 of PEP 257 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 the 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.