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.
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.
""" 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.
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.
""" 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.
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.
""" 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.