The OpenDevStack documentation
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 documetation as code. This 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 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.
Documentation is spread across multiple repositories. In each repository, there is a
docs folder containing the documentation. We use one "distributed" component named
opendevstack (see Component structure documentation), and each
docs folder adds one or more named modules into that component. The navigation for the component is located in the
Additionally, we have the
ods-documentation repository which contains the Playbook and the
ods-docs-ui repository containing UI customization.
A guide for building the documentation locally is provided in the ods-documentation README.
Issue a pull request against the repository containing the documentation you add / modify. Once this is merged, the documentation website will get updated automatically (via a daily cronjob).
The documentation will be build on Travis and pushed back to the ods-documentation repository.
The .travis.yml file is located in the