Docstring formats in Python

Docstring stands for “documentation string” which is a special comment in Python. Elements of interest such as functions, classes, methods and variables are described using the docstrings. The docstrings are not only meant for the developers but also the users.

There are quite a few syntax conventions available for writing docstrings in Python, but it is always advised for a developer to stick to one particular syntax for the entire code of a project.  Lets see the popularly used docstring formats in Python.

reStructuredText

Since, reST is the default format used by Sphinx to generate docs, it is widely used and the most popular. Not only it is used in docstrings but also widely used as a Markdown format for documenting, for e.g. in GitHub for documenting projects.

Example:

"""
This is a an example of reST style docstring.

:param param1: Description of first param.
:type param1: str
:param param2: Description of second param.
:type param2: int
:returns: Description of what is returned.
:rtype: str
:raises MyError: Description of error.
"""

You can refer to this tutorial for more details about the reST documentation.

Googledoc

The Google docstring style is used and supported by Google. This style is also interpreted by Sphinx. It is also popular and used in several forms, Numpydoc is a kind.

Example:

"""
This is an example of Google style docstring.

Args:
    param1 (str): Description of first param.
    param2 (int, optional): Description of second param.

Returns:
    str: Description of what is returned.

Raises:
    MyError: Description of error.
"""

More examples of Google style Python docstrings can be found in this documentation.

Numpydoc

Numpy have their own docstring format which they recommend to use. It is based on the Google docstring format and also uses some reST syntax elements. It is also usable by Sphinx and needs the numpydoc extension, so that the docstrings will be handled correctly. You can refer to this documentation for using the Numpy docstring format.

Example:

"""
This is an example of Numpy style docstring.

Parameters
----------
first : str
    Description of first param.
second : int, optional
    Description of second param.

Returns
-------
str
    Description of what is returned.

Raises
------
MyError
    Description of error.
"""

More examples of Numpy style Python docstrings can be found in this documentation.

Documentation in GraphSpace Python client library:

We have adopted the Google Style docstrings for documenting the code of the GraphSpace Python library. It is easy, flexible and also readily interpreted by Sphinx for external docs generation.

 

One thought on “Docstring formats in Python

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s