Managing Documentation

We use Sphinx for building the documentation. Pages are written in reST notation. Consult the reStructuredText Primer for details on the markup notation.

The documentation is kept in the Gitlab repository of the project, in folder:

https://git.garr.it/cloud/web

The process of generating the HTML pages is automated though a Makefile in the directory web.

Just issuing in that directory:

$ make

will generate the pages in directory:

build/dirhtml

Consult the README.md for further information on the process.

One you are happy with the result, perform:

$ git commit -a
$ git push

This will merge your changes into the GitLab repository. A cron job on the server cloud.garr.it will periodically (every 15th minute) pull the pages to the server and update the web pages.

Styles

The CSS used to render the pages is in: web/_static/styles/cloudita.ss.

Templates

The site uses the basic builtin template, which is defined on github.

The template is specialized for different pages by custom variables defined in the file conf.py. In particular, custom sidebars are used, by setting the variable html_sidebars, to map document file names to template names:

html_sidebars = {
    # Sidebar on doc pages:
    'doc/**': ['smarttoc.html', 'searchbox.html'],
    # no sidebar:
    'compute/**': [],
    'apps/**': [],
    'community/**': [],
    'index': [],
}