1.3. Writing documentation¶

1.3.1. Introduction¶

All the documentation is located in the doc directory. We use the Sphinx formatting engine to compile the documentation source code into fancy formatted HTML or PDF.

The source files have the extension .rst, and are written in the ReStructuredText (RST) format. RST is in some sense comparable to latex, but more intuitive to use. It also has some specific advantages for documenting software.

All .rst files are part of the source tree, just like the actual source code. Git is also used to keep track of changes in the documentation. Whenever you add a new feature, please add the corresponding documentation to explain how your new feature can be used effectively. When you add a significant feature, also update the file ref_features.rst and ref_releases.rst.

1.3.2. Building documentation¶

There is a makefile to generate the documentation based in the source code:

cd doc; make html

If you don’t want to rebuild the documentations with sphinx every time you make a change, you can use the sphinx-autobuild tool available through PyPI. Installation is pretty much like any other PyPI package:

pip install --user sphinx-autobuild

If you are using sphinx-autobuild the command is as follows:

(cd doc; firefox http://localhost:8000 &; make livehtml)

This sets up a server at localhost:8000 and rebuilds the website whenever you make a change to the source files. Just like any other process, you can stop it with Ctrl-C

1.3.3. Common issues¶

When sphinx reports errors or warnings, please fix these in the .rst files and the doc strings in the source code. Keep in mind that only the errors and warnings are shown for files that changed since the last call to make html. If you want to see all errors and warnings, then run make clean; make html.

The following problems are often encountered:

Duplicate labels

When the same label is defined in two places, they become useless. To avoid such name clashes, add a unique prefix to all labels in one rst file. This is a bad example (once found in the file download_and_install_mac.rst):

.. _compile_install::

It is safer to use instead:

.. _mac_compile_install::

Indentation and empty-line errors

RestructeredText is sensitive to indentation and blank lines. For example when making bullet points, the following formatting must be used:

Some paragraph before.

* This is a bullet point with a lot of text that spans several lines.
  Blah blah blah.
* This is the next

Some paragraph after

This won’t work:

* This is a bullet point with a lot of text that spans several lines.
Blah blah blah.
* This is the next

This won’t work either:

Some paragraph before.
* This is a bullet point with a lot of text that spans several lines.
  Blah blah blah.
* This is the next
Some paragraph after

Overriden methods in subclasses do not get inherited docstrings

Please use the horton.utils.doc_inherit() decorator.

A signature should be added manually to the `__init__` method in Cython

The current behavior of Cython is not compatible with PEP257. The signature gets assigned to the class docstring instead of the __init__ docstring. This is a bug in Cython that should eventually be fixed. See... See https://groups.google.com/forum/#!searchin/cython-users/embedsignature/cython-users/sXtBF2nh5RI/GjcirKOWqBcJ