Skip to content
Switch branches/tags

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time

The EOA manual

A manual documenting the whole publication platform and its workflows.

To compile the documentation, install sphinx and sphinx-better-theme (e.g. with pip install -U Sphinx sphinx-better-theme), on a Linux machine add ~/.local/bin to your $PATH, and run make html for the HTML documentation. Other formats (PDF, EPUB) are available, too.

We are using an extra theme for styling: You can install it with pip install -U sphinx-better-theme. Otherwise just revert the variable html_theme in to alabaster or classic (amongst others, check for a complete list of built-in themes).


make html

to build an HTML version of this documentation. However, the whole EOA infrastructure consists of many other projects. This manual serves as an entry point to all the projects, a list is found in subprojects. The next section explains how to pull together the different manuals to aggregate them in one single site.


Use python3 in order to collect all the tools of the EOA cosmos to create one big documentation site.

A few edits need to be done before proceeding.


The script expects a config file that sets the following values in the category [general]:

  • base_dir: Path to the repositories of the sub-projects
  • docserver: Path to the directory of the webserver
  • subprojects: The names of the sub-projects for which documentation is to be created

On tool level

Create documentation

On root level of the tool, create the basix sphinx files with

sphinx-quickstart -a "Author" -l en --ext-intersphinx --extensions sphinx.ext.autosectionlabel docs

Template file

In order to create a link back to the main page, create a template file called layout.html in the directory _templates, containing

{% extends '!layout.html' %}

{%- block header %}
    {%- if theme_showheader|tobool %}
        <header id="pageheader"><h1><a href="{{ pathto(master_doc) }} ">
        {{ docstitle }}
            <h3><a href="../">Main Documentation Page</a></h3>
    {%- endif %}
{%- endblock %}


Project information

Edit the variables project, copyright, author and release to your liking.


For consistency and mobile-friendliness, we are using a theme called better. In the import section of, add

from better import better_theme_path
html_theme_path = [better_theme_path]

and set the variable html_theme to better

html_theme = 'better'

If you want to link to other modules, add a mapping to the intersphinx_mapping dictionary. The of this project contains all the links. Just copy the relevant mappings.

Main Documentation (this project)

When you add a new sub-project, add a new mapping to the intersphinx_mapping dictionary.


Add the path to the new sub-project to the subprojects entry in the configuration. It is assumed that all the projects are located in one common directory, e.g. dev.

Workflow (on server)

  • Write documentation, commit and push
  • On server, pull in changes
  • Run
  • Synchronize the local build directory with the web server directory


Manual for the Edition Open Access






No releases published