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