The OpenDevStack documentation

OpenDevStack documentation is build with Antora.

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

ods-core

ods-core

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

ods-jenkins-shared-library

ods-jenkins-shared-library

ROOT

ods-provisioning-app

ods-provisioning-app

ROOT

opendevstack.github.io

commons

getting-started, ROOT

How to build the site locally?

A guide for building the documentation localy is provided in the ods-documentation project.

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.