There is an official specification on how you should format your docstrings, called PEP 0257. Many people don’t strictly follow this format and use a format that is supported by documentation generation tools like Doxygen, Epydoc, and Sphinx. Formats include (taken from StackOverflow):
Formats
Python docstrings can be written following several formats, as the other posts showed. However, the default Sphinx docstring format was not mentioned and is based on reStructuredText (reST). You can get some information about the main formats in this blog post.
Note that the reST is recommended by the PEP 287.
The following are the main used formats for docstrings.
- Epytext
Historically a _javadoc_ like style was prevalent, so it was taken as a base for Epydoc (with the called Epytext format) to generate documentation.
Example:
"""
JavaDoc Style
@param param1: this is the first param
@param param2: this is a second param
@return: this is a description of what is returned
@raise keyError: raises an exception
"""
- reST
Nowadays, the probably more common format is the reStructuredText (reST) format that is used by Sphinx to generate documentation. Note: it is used by default in JetBrains PyCharm (type triple quotes after defining a method and hit enter). It is also used by default as the output format in Pyment.
Example:
"""
reST Style
:param param1: this is the first param
:param param2: this is a second param
:returns: this is a description of what is returned
:raises keyError: raises an exception
"""
Google has its own format that is often used. It also can be interpreted by Sphinx (i.e., using Napoleon plugin).
Example:
"""
Google Style
Args:
param1: This is the first param.
param2: This is a second param.
Returns:
This is a description of what is returned.
Raises:
KeyError: Raises an exception.
"""
Even more examples
- Numpydoc
Note that Numpy recommends following their own numpydoc based on Google format and usable by Sphinx.
"""
My numpydoc description of a kind
of very exhaustive numpydoc format docstring.
Parameters
----------
first: array_like
the 1st param name `first`
second :
the 2nd param
third : {'value', 'other'}, optional
the 3rd param, by default 'value'
Returns
-------
string
a value in a string
Raises
------
KeyError
when a key error
OtherError
when the other error
"""
Converting/Generating
It is possible to use a tool like Pyment to generate docstrings to a Python project not yet documented automatically, or to convert existing docstrings (can be mixing several formats) from a format to the other one.
Note: The examples are taken from the Pyment documentation