27.1. Documentation of Python Code#

Python code can be documented mostly automatically if the module containing the functions/classes can be imported without error or modification of the path. Please have a look at the autodoc documentation how to automatically add python documentation to the sphinx document tree.

For this automatic documentation to work the docstrings must be valid reStructuredText:

def dummy_function_example(name, foo=None):
    """
    The docstring in the function should fully explain what the function is
    for and how to use it

    * this is a bullet list
    * with multiple entries and some text in *italic* and even **bold**.
      The bullet list items can span multiple lines which are indented

    .. warning:: bullet (as well as enumerated) lists have to start and end
       with an empty line

    1. Single backquotes are for **references** to other documented items.
       For example `basf2.Module` will link to the documentation of the class
       Module in the python module basf2. A different link name and link
       target can be specified with <>: `Module class <basf2.Module>` will
       link to basf2.Module but the link will read "Module class"
    2. Double backquotes are for ``literal text``.

    .. warning:: this is different to markdown where single backquotes are
       usually used for literal text

    3. Links to external websites are usually of the form `Link Text <http://example.com>`_.

    .. note:: there is an underscore at the end of links

    4. math is supported either inline :math:`f(x) = \sum_{x=i}^N x^i` or as
       display verssion:

       .. math::

          f(x) = \sum_{i=1}^N x^i

       .. seealso:: `Math support in Sphinx <http://www.sphinx-doc.org/en/stable/ext/math.html>`_
    5. The easiest way for code example is the "doctest" syntax: Start a new
       paragaph after an empty line with ``>>>`` followed by the python
       statements and (optionally) the expected output of these statements.

       >>> dummy_function_example("some name", foo="bar")
       "Hello some name, Lord of bar"

       .. seealso:: `Showing code examples <http://www.sphinx-doc.org/en/stable/markup/code.html>`_

    6. To document parameters and return types please use the :ref:`googlestyle` as shown below:

    Note:
      For class members please do not include the ``self`` parameter in this list

    Parameters:
      name (str): Description of the first parameter
       Can also span multiple lines if indented properly
      foo: Second parameter but no type given

    Returns:
      Description of the return value

    See Also:
      Some references to other functions
    """

Using

.. autofunction:: examplemodule.dummy_function_example

this would render something like

examplemodule.dummy_function_example(name, foo=None)#

The docstring in the function should fully explain what the function is for and how to use it

  • this is a bullet list

  • with multiple entries and some text in italic and even bold. The bullet list items can span multiple lines which are indented

Warning

bullet (as well as enumerated) lists have to start and end with an empty line

  1. Single backquotes are for references to other documented items. For example basf2.Module will link to the documentation of the class Module in the python module basf2. A different link name and link target can be specified with <>: Module class will link to basf2.Module but the link will read “Module class”

  2. Double backquotes are for literal text.

Warning

this is different to markdown where single backquotes are usually used for literal text

  1. Links to external websites are usually of the form Link Text.

Note

there is an underscore at the end of links

  1. math is supported either inline \(f(x) = \sum_{x=i}^N x^i\) or as display verssion:

    \[f(x) = \sum_{i=1}^N x^i\]

    See also

    Math support in Sphinx

  2. The easiest way for code example is the “doctest” syntax: Start a new paragaph after an empty line with >>> followed by the python statements and (optionally) the expected output of these statements.

    >>> dummy_function_example("some name", foo="bar")
"Hello some name, Lord of bar"

    See also

    Showing code examples

  3. To document parameters and return types please use the Google Style Docstrings as shown below:

Note

For class members please do not include the self parameter in this list

Parameters

  • name (str) – Description of the first parameter Can also span multiple lines if indented properly

  • foo – Second parameter but no type given

Returns

Description of the return value

See also

Some references to other functions