CSO Documentation
=================

Using the Sphinx system for python documentation.

To build the documenation from here, use:

    make html


Installation of Sphinx
-----------------------

The 'Sphinx' python package should be installed.
Try if 'sphinx-quickstart' is available.
If not available, take a look at [Installing Sphinx](https://www.sphinx-doc.org/en/master/usage/installation.html).


Configuration of documentation
------------------------------

To initialize this this documentation, the following configuration was used:

    sphinx-quickstart \
      --sep \
      --project='CSO' \
      --author='Arjo Segers' \
      --ext-autodoc \
      --ext-intersphinx \
      --ext-mathjax \
      --no-batchfile
  
The following entities have been created now:

* 'source' directory to hold the documenation source files;
  initially the following files are created:
  
  * conf.py    : configuration file;
  * index.rst  : source of the main page of the documentation;

* 'build' directory to hold the generated documenation;

* 'Makefile' : make commands.

In the 'source/conf.py' file created in this way,
the following changes were made manually:

* The location of the python modules was added to the search path:

      # If extensions (or modules to document with autodoc) are in another directory,
      # add these directories to sys.path here. If the directory is relative to the
      # documentation root, use os.path.abspath to make it absolute, like shown here.
      #
      import os
      import sys
      sys.path.insert(0, os.path.abspath(os.path.join(os.pardir,os.pardir,'py')) )

* Added default options for 'Autodoc' entries, 
  these are used to create documentation out of Python modules.

* Added default options for 'InterSphinx' references.

* The html theme was changed for a less default layout;
  this requires that the 'html_sidebars' section is commented:

    html_theme = 'bizstyle'

The initial documentation could be created using:

    make html

