Documenting the code

Requirements

  • Sphinx (installed by default with anaconda)

    pip install sphinx
    

Automatic code documentation with autodoc

The Sphinx autodoc extension automatically includes our Python modules documentation in the generated Sphinx documentation.

Addind a new module documentaiton to the build

It is most likely not practical to iclude all of our apps Python modules in the build. Only the modules and classes with the most extensive documentation (docstrings), and the ones where most developer updates are expected should be included.

To add another module’s documentation to the build, add a new entry to the doc/code/modules.rst file, with the correct relative Python path to the module. For example, the views.py documentation is included by:

Tools
-----
.. automodule:: pyidi.tools
    :members:

For more information, see the autodoc documentation.

Docstring style: reStructuredText

Example:

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