===================================
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
<https://devguide.python.org/documenting/#restructuredtext-primer>`_
or this `Cheat Sheet
<http://docutils.sourceforge.net/docs/user/rst/cheatsheet.html>`_.

For documenting Python APIs (modules, classes, functions, etc.) I
favor the *Google style* of reST, most of which can be learned from
`this example
<https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html>`_
(`HTML version <example_google.html>`_).  More generally, the `Google Python
Style Guide <http://google.github.io/styleguide/pyguide.html>`_ 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.