Allegro Documentation

In Allegro we document things with the aid of Sphinx. 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.

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.

Documents under version control

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

• The Allegro Staff Guide (this document), which is the document for Allegro Members
• The Allegro User Guide to give visitors the information they need to work on Allegro computers
• The allegroUtils Documentation as the reference for the python package allegroUtils, that is developed by Allegro
• The Allegro Data Reduction Cookbook.

All Allegro members can contribute to these documents by loading them from the GITHUB, following the instructions in Contributing to an Existing Project. 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.