The OpenDevStack documentation

Why we chose Antora

As we release new versions of OpenDevStack with new or changed functionality and configuration, it should always be clear, which documentation applies to which release. Thus we follow the philosophy: manage docs as code. Which means:

  • Storing content in a version control system alongside with the code.

  • Separating content, configuration, and presentation

  • Reusing shared materials (Don’t repeat yourself)

Antora is a static site generator by the same folks behind the AsciiDoctor project that follows this practices. The engine converts a collection of version controlled documentation written in AsciiDoc into an html site. The project, while new, is active and responsive and has already made released v2.0 and is being embraced by static site documentarians, like Fedora, Couchbase, Owncloud, Mule.

How is the documentation organized?

The documentation is contained in the doc subdirectory of every project. Every doc directory is the root of an Antora Component. We have additional projects containing the playbook and the UI customization.

  • ods-documentation

  • ods-docs-ui

We also maintain a third repository ods-guides that provide more complete Guides that refer to multiple OpenDevStack components, like the common:getting-started.adoc guide.

Table 1. Antora components and relevant repositories
github-repo antora component modules



infrastructure-setup, jenkins, nexus, ROOT, shared-images, sonarqube








getting-started, ROOT

How to build the site locally.

After installing Antora according to the Install Antora guide, you need to check out the ods-documentation project and run the playbook.

antora generate site.yml

This fetches the different referenced repositories from github and caches them locally. If you want to preview your local changes, you can use

antora generate site-workspace.yml


antora generate site-workspace-full.yml

The difference is that the latter will take into account all branches, the first option will only build the last branch. Both assume that all ods projects are located side-by-side.

How to contribute documentation

At least you should

  • Fork the required ods-projects

  • Make your changes and push them to your github account

  • Issue a Pull Request against the original repository

How is the documentation built on Github?

The documentation will be build on travis and pushed back to the ods-documentation repository. The travis file is located in the ods-documentation project.

This means, if a "documentation" Pull Request is merged, the documentation is not automatically built and deployed. You should add an entry to the documentation changelog and issue a PR. Only when this is merged, the new documentation is generated.