Generating Documentation with Sphinx
====================================

This README is for generating and writing documentation using Sphinx.
On the repository there should already be the auto-generated files
along with the regular documentation.

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

First install Sphinx. Go to http://www.sphinx-doc.org/en/stable/ or run

::

    pip install -U Sphinx
    pip install -U sphinx-rtd-theme

The eskapade/docs folder has the structure of a Sphinx project.
However, if you want to make a new Sphinx project run:

::

    sphinx-quickstart

It quickly generates a conf.py file which contains your configuration
for your sphinx build.

Update the HTML docs
--------------------

Now we want Sphinx to autogenerate from docstrings and other
documentation in the code base. Luckily Sphinx has the apidoc
functionality. This goes through a path, finds all the python files and
depending on your arguments, parses certain parts of the code
(docstring, hidden classes, etc.).

**First make sure your environment it setup properly. Python must be
able to import all modules otherwise it will not work!**

From the the root of the repository:

::

    $ source setup.sh

To run the autogeneration of the documentation type in /docs/:

::

    ./autogenerate.sh

to scan the pyfiles and generate \*.rst files with the documentation.
The script itself contains the usage of apidoc.

Now to make the actual documentation files run:

::

    make clean

to clean up the old make of sphinx and run:

::

    make html

to make the new html build. It will be stored in (your config can adjust
this, but the default is:) docs/build/html/ The index.html is the
starting page. Open this file to see the result.

Mounting a different repository to vagrant
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

When you want to develop code that is not part of the repository that 
your vagrant is in, you can mount it seperately. This is done by changing
the Vagrantfile, by changing the ``#mount`` line to the path of the repository
that you want to mount:

::

  config.vm.synced_folder "<PATH_TO_REPOSITORY>", "<LOCATION_TO_MOUNT>", id: "esrepo"
    
where the location to mount is e.g. /opt/eskapade.

What is an .rst file?
~~~~~~~~~~~~~~~~~~~~~

R(e)ST is the format that Sphinx uses it stands for ReSTructured
(http://docutils.sourceforge.net/docs/user/rst/quickref.html). It looks
for other RST files to import, see index.rst to see how the **toctree**
refers to other files.
