Sphinx
======

`Sphinx <http://www.sphinx-doc.org/en/stable/>`_ is a tool for generating
documentation from `reStructuredText
<http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html>`_.

It can generate various formats, including HTML and PDF.


Installing Sphinx
-----------------

On RHEL 7 it is enough to install the ``python-sphinx`` package::

    yum install python-sphinx


Editing
-------

On Linux with the ``inotify-tools`` it is easy to have the documentation recompiled
automatically while editing. Just run the following in the base directory of the
documentation::

    inotifywait --monitor --recursive --event close_write --exclude '_build' . | while read l; do make html;done

On OSX you can install `fswatch <https://github.com/emcrisostomo/fswatch>`_ and then run the following::

    fswatch --exclude=_build --monitor=fsevents_monitor --recursive --event Updated --event Created --event Renamed .| while read l; do make html ;done

An even better alternative is `sphinx-autobuild
<https://pypi.python.org/pypi/sphinx-autobuild>`_, which can be installed using
pip::

    pip install sphinx-autobuild

It can then be called like this::

    sphinx-autobuild /path/to/sphinx/repo /path/to/sphinx/repo/_build/html/