IEM Documentation

This directory contains the IaC Executor Manager documentation (in the docs_files directory), in the form of a Sphinx project with reStructuredText source files.

TODO: fill the skeleton

The files provided in the docs_files directory are merely a skeleton of the target documentation. The authors of this component should fill this skeleton with proper content.

The main task to accomplish here is to provide adequate *.rst (reStructuredText) files, corresponding to specific subpages of the target documentation. The names of the new docs files can be added by the authors to the toctrees in the index.rst file in order to add links to the corresponding subpages to the table of contents (in the sidebar). However, simply providing the *.rst files with documentation content is fine as well - 7bulls will take care of integrating them in such case.

Some information needs to be added to the already provided files as well. The files include:

• conf.py - the configuration of the Sphinx docs generator
• index.rst - the home page of the documentation
• 01-intro.rst - the page with an outline of the component
• contact.rst - the page with contact info

Some of the information to provide is outlined and indicated with TODO comments in these files.

reStructuredText is a markup language designed for writing technical documentation. A primer on its most crucial elements can be found here.

Some PIACERE components with already prepared documentation following this or a similar style include:

• IOP
• ISR
• IDE (this one uses Markdown as its documentation source language)

Documentation building

The documentation can be built using Sphinx. First, install the requirements using:

pip3 install -r requirements.txt

or, if you wish to use a virtual environment:

python3 -m venv venv
source ./venv/bin/activate
pip3 install -r requirements.txt

Next, in order to generate the result HTML documentation, run the following commands:

cd docs_files
make clean html

The result documentation can then be found in the docs_files/_build directory.

TODO: documentation building and deployment in CI/CD

The documentation will eventually be automatically built and deployed to a server (so that it is available to end users) as part of the CI/CD process. 7bulls will take care of this aspect.