Updated documentation.

    git  clone  git@ci.tno.nl:cams/cso.git

Online documenatation

---------------------

Documenatation

--------------

A documentation is available online via the *Gitlab Pages*:

It is updated automatically when changes are pushed.

Eventually create a local version of the documentation from its source files using:

    make docu

and browse to:

    doc/build/html/index.html

Note that the documenation requires 'sphinx', 

which is usually part of your python distribution.

Tutorial

--------

    ./bin/cso rc/tutorial.rc

Eventually first re-create the documentation from the its source files:

    make docu

Note that the documenation requies 'sphinx', 

which is usually part of your python distribution.

  sphinx-quickstart 2.4.0

If not available yet, try to install using one of the following methods.

Install Sphinx

--------------

Try if it is possible to download and install Sphinx using 

one of the standard installation commands.

    pip install sphinx

Build Sphinx from source 

------------------------

Download the latest version from the

`Sphinx homepage <http://sphinx-doc.org/index.html>`_,

for example::

* To build Sphinx from source, download the latest version from the

  `Sphinx homepage <http://sphinx-doc.org/index.html>`_, for example::

    Sphinx-3.0.3.tar.gz

Configuration

=============

The source of the documentation is located in (subdirectories of):

The source of the documentation is located in (subdirectories of)::

  ./doc/

  doc/

In this directory, the Sphinx quick start command has been called::

       documentation

Online publication with Gitlab Pages

====================================

The repository is hosted on `Gitlab <https://about.gitlab.com/>`_ server.

This has also the option to automatically generate the documenation and store 

the resulting html files on a web server associated with the repository, which are called the *Gitlab Pages*.

The following steps describe the steps that were taken.

Create a GitLab Runner

----------------------

A '*GitLab Runner*' is a '*Docker*' container that will perform the actual jobs of, 

in this case, generating and uploading the documentation.

This should run on a local server that could be contacted by the Gitlab server.

When a '*GitLab Runner*' is already available, one could go to the next item.

For this project a GitLab Runner has been created using the following steps.

1. Install '*Docker*' on the local server. The desktop version is available from: `www.docker.com/products/docker-desktop <https://www.docker.com/products/docker-desktop/>`_.

2. Start Docker Desktop. This starts a docker server in the background that enables you to run Docker containers.

3. Open a terminal.

4. Download the ``gitlab-runner`` image from ``gitlab.com``, install it and start it::

     docker run -d \

         --name gitlab-runner \

         --restart always \

         -v /srv/gitlab-runner/config:/etc/gitlab-runner \

         -v /var/run/docker.sock:/var/run/docker.sock gitlab/gitlab-runner:latest

   Basically, this is a customized '*Docker*' image with a standard Linux distribution and the necessary

   tools for running GitLab CI/CD pipelines. Every time you commit and push changes to the GitLab

   repository, the container (i.e., the running instance of the Gitlab image) will execute the pipelines

   (provided your Docker server is running and the runner is registered in GitLab, see below).

5. Check it in your Docker Desktop GUI, click on '*Containers*' in the

   left menu and you'll see gitlab-runner listed with a green dot in front of it, showing that the

   container is running. If you click on the name gitlab-runner, you'll see the logs of the runner.

   Since you do not have a configuration yet, there will be error messages like this::

      2025-01-21 14:26:23 ERROR: Failed to load config stat /etc/gitlab-runner/config.toml: no such file or directory  builds=0 max_builds=1 

   This will be remedied in the next step.

Registration of the runner

--------------------------

The runner needs to be registrated for the GitLab Project, or for its group.

The following steps were taken to registrate the runner for the "CAMS" group holding this project.

1. Open the Gitlab homepage of the group.

2. In the side bar, select ``Settings > CI/CD``.

3. Expand the ``Runners`` section.

4. Check if a already a runner has been registrated. If no runner was registrated yet, use the following steps.

  1. In the side bar, open ``Build > Runners``.

  2. Enable ``Run untagged jobs``.

  3. Click on ``[Create runner]``.

  4. Copy the command that is shown, which looks like::

      gitlab-runner register  --url https://ci.tno.nl/gitlab  --token abcdEFGHIjklmnOPQRstuvw

  5. Login on the server where the ``gitlab-runner`` Docker immage was installed and open a terminal.

  6. Paste the copied command as part of the following command::

      docker  exec \

           --interactive  \

           --tty \

           gitlab-runner \

           gitlab-runner register  --url https://ci.tno.nl/gitlab  --token abcdEFGHIjklmnOPQRstuvw

     Provide the following information when asked for:

     * For the GitLab instance URL, choose: ``https://ci.tno.nl/gitlab``

     * For the name, use the default

     * For executor, use: ``docker``

     * For image, use: ``ubuntu:latest``

Create a CI/CD pipeline

-----------------------

The actions to be performed to create the documentation are::

        cd doc

        make html

This should now be done when code is changed using a '*pipeline*'.

1. Goto main page of the GitLab project.

2. Open the ``[+]`` drop-down, select ``create file``, and create a file named::

     .gitlab-ci.yml

   The content should look like::

      # The Docker image that will be used to build your app

      image: python:3.11

      # Functions that should be executed before the build script is run

      before_script:

        - pip install numba

        - pip install sphinx

      stages:

        - deploy-pages

      pages:

        stage: deploy-pages

        rules:

          - if: '$CI_COMMIT_BRANCH == "master"'

            when: always

        script:

          - cd doc

          - make html

          - cd ../..

          - mkdir public

          - cp -r doc/build/html/* public

        artifacts:

          paths:

            - public

   Save and commit the file.

   This tells to create a pipeline to:

   * setup the correct python environment to generate the documentation;

   * create the documentation (in a clone of the current repository);

   * create a directory named ``public`` and to copy the documents into there;

   * tell that the end result is located in the just filled directory ``public``.

   This is only done for changes in the master branch, as otherwise the documentation from a development branch

   will be shown online.

3. When the above instruction file was committed, the pipeline is started immediately as this is a change of the source code.

   In the side bare open ``Build > Jobs`` for a list of jobs that were run.

   The latest job is probably is probably still running; when finished, click on the status label to open the details.

   Based on the messages, edit the ``yml`` or the source files that might need corrections.

4. If the pipeline was finished correctly, the documentation should have been copied to a web server.

   Goto the main page of the GitLab project, and in the right side bar click on the ``Gitlab Pages`` link to see the result:

       `cams.ci.tno.nl/cso <https://cams.ci.tno.nl/cso>`_