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: https://sphinx-better-theme.readthedocs.io/en/latest/. You can install it with pip install -U sphinx-better-theme. Otherwise just revert the variable html_theme in conf.py to alabaster or classic (amongst others, check https://rtd-sphinx-theme-sample-project.readthedocs.io/en/latest/ for a complete list of built-in themes).

Use

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.

Aggregation

Use python3 aggregate.py 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.

Configuration

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 }}
        </a></h1>
            <h3><a href="../">Main Documentation Page</a></h3>
        </header>
    {%- endif %}
{%- endblock %}

Configuration

Project information

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

Theme

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

from better import better_theme_path
html_theme_path = [better_theme_path]

and set the variable html_theme to better

html_theme = 'better'

Intersphinx

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

Main Documentation (this project)

`conf.py`

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

`config.cfg`

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 aggregate.py
Synchronize the local build directory with the web server directory

EditionOpenAccess/eoa_manual

About

Resources

Stars

Watchers

Forks

Releases

Languages