Versioned documentation

[mbfm]

When reading the documentation, a user should be able to look at documentation for older openDuT releases. Currently, it only displays changes for the newest version.

Current workflow

We use mdbook to create our documentation site.

• The deployment job for the homepage: .github/workflows/job-homepage.yaml
• The following CI command creates the documentation: cargo ci doc homepage build here
• Then the GitHub Action deploy homepage is used to publish the page.

Otterdog

The GitHub organization is managed by Eclipse. Therefore we do not have direct administrative rights on the GitHub repository, but we can configure it through otterdog:

• relevant otterdog configuration is here
• See also gh_pages_build_type in otterdog documentation here

Solution options

At the moment the gh-pages artifact is not persisted in a GitHub repository. If we were to create a new documentation at each run we need to come up with a solution to keep the old page and new versions with each publication. There is an open issue in the mdbook repository regarding this topic.

• Use GitHub cache
• Store artifact as compressed file and add to the page itself
• Switch back to publishing on a repository

Versions

Which versions would we like to keep?

• Released version documentation: v[0-9]+.[0-9]+.[0-9]+, e.g. v0.7.0
• Latest version should link to the latest published version

Idea: Also add documentation to the released artifacts here.