Sphinx and RST syntax guide (0.9.3)

previous | next | modules | index

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
Author: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:

    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 function1() docstring.

function1(arg1, arg2, arg3)[source]

returns (arg1 / arg2) + arg3

This is a longer explanation, which may include math with latex syntax \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 <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
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
Parameters:
  • arg1 (int, float,...) – the first value
  • arg2 (int, float,...) – the first value
  • arg3 (int, float,...) – the first value
Returns:

arg1/arg2 +arg3
Return type:

int, float
Example: 
>>> import template
>>> a = template.MainClass1()
>>> a.function1(1,1,1)
2

Note

can be useful to emphasize important feature

See also

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 <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``

        **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()

Search

Enter search terms or a module, class or function name.

This page: Show source.

Table Of Contents

© Copyright Thomas Cokelaer.
Last updated on Aug 14, 2014.
Created using Sphinx 1.2.2.
previous | next | modules | index