Migrate and deploy the documentation with the AsciiBinder

Motivation

In Red Hat environments there is a lot of effort to migrate documenation from DocBook XML format to AsciiDoc and a framework was built called AsciiBinder. It is already successfully used in the OpenShift project and supports multiple distributions of the software. The current documentation is rendered as a single HTML standard AsciiDoctor Maven package. It is not optimal to use and is now quite large and hard to handle. For the reason, we have already migrated to AsciiDoc and have a good modular documentation structure a migration to AsciiBinder is not hard and would give us the following benefits:

  • Web rendering framework with Java Script support for collapsable navigation
  • Just the selected piece of documentation is shown instead of a reference in one large document
  • Stylesheet and theming support to customize the layout for the documentation
  • Branch support and versioning

During the week of DevJam migrate and deploy the documentation with the AsciiBinder Framework for the OpenNMS project for Horizon and Meridian.

  • Step 1: Build and deploy with Bamboo from a GitHub opennms-doc repository
  • Step 2: Migrate Install, Admin and User Guide to AsciiBinder with versioning
  • Step 3: Separate Minion documentation from the Install Guide

Folks

  • Ronny Trommer

Links