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
*********