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

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