Contributing to documentation

We use the reStructuredText format to write our documentation because this is the de-facto standard for Python documentation. We use Sphinx tool to generate documentation from reStructuredText files.

Published documentation lives on Read the Docs: https://cekit.readthedocs.io/

reStructuredText

A good guide to this format is available in the Sphinx documentation.

Local development

Note

The documentation has its own requirements.txt. As above we would recommend using Virtualenv to use a clean development environment. The Ansible scripts above will install all documentation pre-requisites as well.

Support for auto generating documentation is avialable for local development. Run the command below.

make preview

Afterwards you can see generated documentation at http://127.0.0.1:8000. When you edit any file, documentation will be regenerated and immediately available in your browser.

Guidelines

Below you can find a list of conventions used to write CEKit documentation. Reference information on reStructuredText may be found here.

Headers

Because reStructredText does not enforce what characters are used to mark header to be a certain level, we use following guidelines:

h1 header
=========

h2 header
---------

h3 header
^^^^^^^^^

h4 header
*********