Python docstrings

Numpy docstrings

Guide: https://numpydoc.readthedocs.io/en/latest/format.html

This is the style used by the numpy package, which actually uses sphinx for its API. It is a large and spacious style with lots of empty lines between parts of the documentation. It uses clear titles for organisation of the paramters, returns and errors. Parameters are described clearly with a name, type and description over two lines. This makes it very clear and easily readable with the naked eye. It takes up a large amount of space in the code but makes scan reading easy.

Google docstrings

Guide 1: https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html

Guide 2: https://google.github.io/styleguide/pyguide.html

Google docstrings are defined as part of googles python guide. They are slightly more condenced than numpy docstrings. This is done by using a single line for each title and for each parameter, return and warning. The format means they are still readable though harder to scan than numpy. They are also designed with extra text and long descriptions in mind.

reStructuredtext /SPHINX

Guide 1: https://peps.python.org/pep-0287/

Guide 2: https://sphinx-rtd-tutorial.readthedocs.io/en/latest/docstrings.html

reStructuredText docstrings are compact and designed more for computer readability than human. They use tags for different information and prefer shorter descriptions. These match with the rest of the Sphinx pages which are also writen in reStructuredText. Sphinx autodoc however can read all the docstrings presented here.

Epytext

Guide: https://epydoc.sourceforge.net/manual-epytext.html

This is another compact style using tags with the @ sign. It splits types and descriptions of parameters and doesn't provide any section labels. It is easier to read than reStructuredText but still designed more for the computer than the human. Its dense description makes scan reading harder.

Choosing...

There is certainly a choice to be made between these styles. The first consideration should always be compatibility. If you are using an automatic documentation method you need to match a style it recognises. Second to this you should consider matching existing documentation in the same project to keep it consistent. The final consideration for compatibility is if you are using an IDE then some of them can automatically detect some documentation styles. This allows it to perform type checking in your code. This can be helpful in identifying integration issues between functions while writing the code.

Assuming no other limitations readability should be your guide. Chose the documentation you find easiest to read and would most like to see in your code. For order and structure Numpy with its titles and formatting is great. For conciseness Epytext can seem perfect with none of the separators but might actually be longer than Google with its single line parameters.

Think about your choice because you could be looking at that docstring years from now.

Page updated

Report abuse