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/
A good guide to this format is available in the Sphinx documentation.
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.
Below you can find a list of conventions used to write CEKit documentation. Reference information on reStructuredText may be found here.
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
*********