.. _tutorial_sphinx_general:

##########################################
General Sphinx Information
##########################################

******************************************
Architecture
******************************************

The EVerest documentation consists of three parts:

#. 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.

#. 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.

#. 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.

******************************************
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 :ref:`How To: Act <tutorial_act>` 
for more information.

Use act to run the workflow locally:

.. code-block::

    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.