Writing Documentation for Solutions

Restructured Text

For documenting code and features of Solutions, reStructuredText (reST) is recommended, as many powerful tools are available for converting this format into other formats, including HTML, PDF, etc.

It is very easy to write documents in the reST format. After looking at one or two examples you will know most of what you need. Examples are easy to find, for example click on the “Page source” link at the bottom of this page. You can also look at the (very short) reStructuredText Primer or this Cheat Sheet.

For documenting Python APIs (modules, classes, functions, etc.) I favor the Google style of reST, most of which can be learned from this example (HTML version). More generally, the Google Python Style Guide is highly recommended for writing Python code.

Adding Documentation to Solutions

To add documentation, add new .rst files to the Solutions/Python/Documentation directory and edit the file index.rst to contain references to them. To include the docstrings contained in a Python module, say mymodule.py, add the text:

.. automodule:: mymodule
   :members:

For example, see the file dbxml.rst in the Documentations directory.

Generate Documentation in HTML Format

To compile the documentation, start by creating a virtual environment for development as described in the file README.Devel. Then activate this environment, change to the Documentation directory, and run make html:

workon sol
cd Documentation
make html

If you prefer documentation in PDF format, then use:

make latexpdf

This requires that LaTeX is installed.