9.10. General Sphinx Information

9.10.1. Architecture

The EVerest documentation consists of three parts:

1. The handwritten documentation of EVerest/EVerest.

   It is located in the doc directory of the EVerest/EVerest repository. The purpose is to provide a high level documentation of the EVerest project/framework, tutorials, tools, etc.

2. The automaticcally generated documentaiton

   This part is generated by github actions when running the deploy-sphinx-doc.yml workflow located in EVerest/EVerest. It includes human readable documentation of interfaces, modules and types that are defined by json files in the EVerest/everest-core repository.

3. The handwritten documentation of EVerest/everest-core.

   This part is automaticcally included by the generation of the second part of the documentation. It is located in the doc directory of the EVerest/everest-core repository. The purpose is to provide the possibilty to expand the auto generated documentation by custom handwritten documentation. With this it is possible to use all features of reStructuredText/Sphinx as including images, tables, etc.

9.10.2. Build the documentation

The documentation is build by the deploy-sphinx-doc.yml workflow located in EVerest/EVerest. It is triggered by a push to the main branch of EVerest/EVerest. The workflow generates the documentation and pushes it to github pages. The documentation is available at http://everest.github.io.

To build the documentation locally, you need to install the tool act to run the github workflow locally. See How To: Act for more information.

Use act to run the workflow locally:

cd EVerest/EVerest
mkdir work0/
cd work0/
act workflow_dispatch -b -W ../.github/workflows/deploy-sphinx-doc.yml -j build-sphinx

The documentation is generated in the work0 directory. Open work0/everest/docs/_build/html/index.html in your browser to view the documentation.