Table Of Contents

Previous topic

3.6.1. Restructured Text (reST) and Sphinx CheatSheet

Next topic

3.6.6. Include test in your docstrings

This Page

3.6.5. How to document your docstrings

Overview

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

3.6.5.1. The docstring

Let us suppose that you have such a docstring:

"""Brief synopsis

This is a longer explanation, which 
may include math :math:`\\alpha`.
Then, you need to provide optional
subsection in this order (just to be
consistent and have a uniform documen
tation Nothing prevent you to switch
the order):
        

:Parameters:
 - `arg1` (int,float,...) - the first value
 - `arg2` (int,float,...) - the first value
 - `arg3` (int,float,...) - the first value
         
:Returns:
    arg1/arg2 +arg3
            
:Returns Type:
    int,float 
       
:Examples:        

>>> import template
>>> a = MainClass()
>>> a.function2(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.
"""

3.6.5.2. Autodocument your module

Then, you can use the automodule directive as follows:

.. automodule:: docstring.py

which gives the following interpretation: