.. highlight:: bash

Allegro Documentation
=====================

In Allegro we document things with the aid of `Sphinx <http://sphinx-doc.org/>`_.
This is a tool that makes it easy to create documents in various formats by
using so-called reStructuredText as an input resource.
Moreover, Sphinx you can automatically incorporate your docstrings from
python-functions to auto-generate a full documentation of your python modules. 

A necessary step to make that possible is to use special syntax and/or
indentation in your input files and/or docstrings, which is then
automatically converted into headlines, tables, cross-links, math equations, etc.
A resource for how to format your text is the
`reStructuredText Primer <http://sphinx-doc.org/rest.html>`_.

.. note: HTML-Documents that are created with Sphinx have a ``Show Source``
   button that displays the underlying reST file. This is particularly useful
   when you would like to know how a certain feature (e.g., a *Note* box) is
   implemented. 

It can be useful, when editing the source files for Allegro documents, to make a temporary build of your cloned copy, in order to check for errors. Typical commands to do this would be ::

    cd <dir where my copy of the relevant .rst files are>
    sphinx-build -b html . <directory where you want to html files to go>

Somewhere off your home pages for example.

Note that sphinx needs a package named ``numfig`` which is available on chaxa, but not on the other Sterrewacht machines.

.. _`allegro-docs`:

Documents under version control
-------------------------------

Currently, there are four documents that are the main resources for working
with Allegro computers:

* The `Allegro Staff Guide <http://home.strw.leidenuniv.nl/~alma/doc/allegroStaffGuide>`_
  (this document), which is the document for Allegro Members
* The `Allegro User Guide <http://home.strw.leidenuniv.nl/~alma/doc/allegroUserGuide>`_
  to give visitors the information they need to work on Allegro computers
* The `allegroUtils Documentation <http://home.strw.leidenuniv.nl/~alma/doc/allegroUtils>`_
  as the reference for the python package ``allegroUtils``, that is developed
  by Allegro
* The `Allegro Data Reduction Cookbook <http://home.strw.leidenuniv.nl/~alma/doc/allegroDRC>`_.

All Allegro members can contribute to these documents by loading them from the
GITHUB, following the instructions in :ref:`AG-s-git-contribution`. Their locations under the repository directory ``$ALLEGRO_GIT`` are as follows:

================================ ================================ ===============================
Document                          Repository                       Update command
================================ ================================ ===============================
Allegro Staff Guide               ``doc/allegroStaffGuide.git``    ``update_doc allegroStaffGuide``
Allegro User Guide                ``doc/allegroUserGuide.git``     ``update_doc allegroUserGuide``
Allegro Project Management        ``doc/allegroUtils.git``         ``update_doc allegroUtils``
allegro Data Reduction Cookbook   ``doc/allegroDRC.git``           ``update_doc allegroDRC``
================================ ================================ ===============================

The command ::

    $ update_doc <document name>

not only updates the system-wide documentation, but also generates the ``html`` and ``pdf`` files, which are copied respectively to the webspace and the ``doc`` directories on ``lustre``.