# 2. Example on how to document your Python docstrings¶

Overview

This example shows how to document your docstrings and how to interpret it within your RST document.

Date: August 14, 2014 Thomas Cokelaer

Let us consider a python module called template (see bottom of the page). With Sphinx, you can auto-document this module by including the following code within a RST document:

.. automodule:: template
:members:
:undoc-members:
:inherited-members:
:show-inheritance:


This code will scan the module template.py, find all its members, undocumented members and add their docstrings. It will also include documentation from inhereted classes (if any) and show the inheritance tree.

Warning

Your modules must be visible that is partof your PYTHONPATH variable otherwise Sphinx is not able to find them.

There is a lot of tunable possibilities. For instance, you can include only some members if needed.

## 2.1. Auto documented class (method 1)¶

The previous code generates automatically the following documentation for the class MainClass1 contained in the module template.py

This module illustrates how to write your docstring in OpenAlea and other projects related to OpenAlea.

class MainClass1[source]

Bases: object

This class docstring shows how to use sphinx and rst syntax

The first line is brief explanation, which may be completed with a longer one. For instance to discuss about its methods. The only method here is function1()‘s. The main idea is to document the class and methods’s arguments with

• parameters, types, return and return types:

:param arg1: description
:param arg2: description
:type arg1: type description
:type arg1: type description
:return: return description
:rtype: the return type description

• and to provide sections such as Example using the double commas syntax:

:Example:

followed by a blank line !


which appears as follow:

followed by a blank line

• Finally special sections such as See Also, Warnings, Notes use the sphinx syntax (paragraph directives):

.. seealso:: blabla
.. warnings also:: blabla
.. note:: blabla
.. todo:: blabla


Note

There are many other Info fields but they may be redundant:
• param, parameter, arg, argument, key, keyword: Description of a parameter.
• type: Type of a parameter.
• raises, raise, except, exception: That (and when) a specific exception is raised.
• var, ivar, cvar: Description of a variable.
• returns, return: Description of the return value.
• rtype: Return type.

Note

There are many other directives such as versionadded, versionchanged, rubric, centered, ... See the sphinx documentation for more details.

Here below is the results of the function1() docstring.

function1(arg1, arg2, arg3)[source]

returns (arg1 / arg2) + arg3

This is a longer explanation, which may include math with latex syntax . Then, you need to provide optional subsection in this order (just to be consistent and have a uniform documentation. Nothing prevent you to switch the order):

• parameters using :param <name>: <description>
• type of the parameters :type <name>: <description>
• returns using :returns: <description>
• examples (doctest)
• seealso using .. seealso:: text
• notes using .. note:: text
• warning using .. warning:: text
• todo .. todo:: text
• Uses sphinx markups, which will certainly be improved in future version
Drawbacks:
• Just looking at the docstring, the parameter, type and return sections do not appear nicely
Parameters: arg1 (int, float,...) – the first value arg2 (int, float,...) – the first value arg3 (int, float,...) – the first value arg1/arg2 +arg3 int, float
>>> import template
>>> a = template.MainClass1()
>>> a.function1(1,1,1)
2


Note

can be useful to emphasize important feature

MainClass2

Warning

arg2 must be non-zero.

Todo

check that arg2 is non zero.

## 2.2. template.py source file¶

The source file is provided for convience here below:

  1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 """This module illustrates how to write your docstring in OpenAlea and other projects related to OpenAlea.""" __license__ = "Cecill-C" __revision__ = " $Id: actor.py 1586 2009-01-30 15:56:25Z cokelaer$ " __docformat__ = 'reStructuredText' class MainClass1(object): """This class docstring shows how to use sphinx and rst syntax The first line is brief explanation, which may be completed with a longer one. For instance to discuss about its methods. The only method here is :func:function1's. The main idea is to document the class and methods's arguments with - **parameters**, **types**, **return** and **return types**:: :param arg1: description :param arg2: description :type arg1: type description :type arg1: type description :return: return description :rtype: the return type description - and to provide sections such as **Example** using the double commas syntax:: :Example: followed by a blank line ! which appears as follow: :Example: followed by a blank line - Finally special sections such as **See Also**, **Warnings**, **Notes** use the sphinx syntax (*paragraph directives*):: .. seealso:: blabla .. warnings also:: blabla .. note:: blabla .. todo:: blabla .. note:: There are many other Info fields but they may be redundant: * param, parameter, arg, argument, key, keyword: Description of a parameter. * type: Type of a parameter. * raises, raise, except, exception: That (and when) a specific exception is raised. * var, ivar, cvar: Description of a variable. * returns, return: Description of the return value. * rtype: Return type. .. note:: There are many other directives such as versionadded, versionchanged, rubric, centered, ... See the sphinx documentation for more details. Here below is the results of the :func:function1 docstring. """ def function1(self, arg1, arg2, arg3): """returns (arg1 / arg2) + arg3 This is a longer explanation, which may include math with latex syntax :math:\\alpha. Then, you need to provide optional subsection in this order (just to be consistent and have a uniform documentation. Nothing prevent you to switch the order): - parameters using :param :  - type of the parameters :type :  - returns using :returns:  - examples (doctest) - seealso using .. seealso:: text - notes using .. note:: text - warning using .. warning:: text - todo .. todo:: text **Advantages**: - Uses sphinx markups, which will certainly be improved in future version - Nice HTML output with the See Also, Note, Warnings directives **Drawbacks**: - Just looking at the docstring, the parameter, type and return sections do not appear nicely :param arg1: the first value :param arg2: the first value :param arg3: the first value :type arg1: int, float,... :type arg2: int, float,... :type arg3: int, float,... :returns: arg1/arg2 +arg3 :rtype: int, float :Example: >>> import template >>> a = template.MainClass1() >>> a.function1(1,1,1) 2 .. note:: can be useful to emphasize important feature .. seealso:: :class:MainClass2 .. warning:: arg2 must be non-zero. .. todo:: check that arg2 is non zero. """ return arg1/arg2 + arg3 if __name__ == "__main__": import doctest doctest.testmod()