Contribute to the documentation

The grouprise documentation for administrators and developers can be found below docs/ in the grouprise repository.

The documentation is rendered via Sphinx.

Most documentation files are written in markdown format (*.md). A few documentation files (especially index files for defining hierarchies) are written as restructured text.

Simply run make doc in order to build the documentation. Afterwards you can browse the generated documentation: build/doc/html/index.html

Markdown format

Markdown is a convenient format for writing formatted text, but sadly our currently used parser (recommonmark) does not offer all structuring capabilities offered by Sphinx.

The following hints may help you:

• referencing a section in a different file:

  • sadly such references need to rely on automatically generated HTML anchors (e.g. configuration/options.html#stylesheets)

  • the path needs to be relative (i.e. add ../ in front, depending on the nesting level of the current document)

• referencing a file:

  • use something like /administration/configuration/options

  • in contrast to referencing a section (see above), the path can be absolute and should not include the .html extension

Graphs (via graphviz)

The graphviz extension for Sphinx allows to use render graphs in documentation files:

.. graphviz::

    graph {
        A -- B -- C;
        A -- D -- C;
    }

Such graphs are (at the moment) only available in rst files.