==========================
Documentation instructions
==========================

TheSyDeKick is documented with Sphinx automated docsring documentation using ReStructuredText.
https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html

Current docstring documentation style is Numpy
https://numpydoc.readthedocs.io/en/latest/format.html

Structure
---------

Documentation of an Entity is defined in `<Entity>/doc`. You can use any of the core entities 
(thesdk, rtl, spice) as an example. 

The idea of the documentation is the following:

* doc/sources/conf.py defines the dependencies of the documenation Sphinx build.

* doc/sources/index.rst defines the title and the structure of the Entity documenation

* doc/sources/sections.rst defines the contents of the documentation so that it can be included `as is`
  to compilation performed at another location. This documentaion is an example of that.

* doc/sources/indices_and_tables.rst is a definition of automated glossary. It is separated from sections and 
  index.rst in order not to repeat the glossaries in compilations at another location.

* documentation is build in `<Entity>/doc` with `make html` . Under `<Entity>` the configure script should 
  generate a Makefile with a recipe `doc` that executes `cd doc && make html`. 


Continuous Implementation build process for documentation
---------------------------------------------------------

Documentation build environment for Sphinx-docstrings build are located in `$THESDKHOME/docs`

CI documentation build process uses a docker configuration 
https://github.com/TheSystemDevelopmentKit/thesdktestimage that has an automated relelease to registry. 
The image is currently a fedora34 image with installed software for building the docs, and there should 
not be need to edit that unless the build process fails due to a missing software. Python dependencies are 
installed during the build by pip3userinstall.sh script.

Aforementioned image is used in the workflow definition file `$THESDKHOME.github/workflows/main.yaml` 
which defines the branch to which the pushes launces execution of a script `$THESDKHOME/CI-helpers/build_docs.sh`.

Conlusion:

* To edit the contents of the documenation, edit the docstrings of the entity python files, 
  the files doc/sources of corresponding entities, and the files under `THESDKHOME/dosc/sources`.
  
* To reconfigure the build environment, modify https://github.com/TheSystemDevelopmentKit/thesdktestimage.

* To configure on which branches the build process is launced, edit `$THESDKHOME/.github/workflows/main.yaml`

* To control the build process, edit `$THESDKHOME/CI-helpers/build_docs.sh`