Migrate documentation to Antora

Motivation

We successfully migrated our DocBook XML style documentation to Asciidoc. After some time the group around AsciiDoctor introduced Antora which became an open-source framework for AsciiDoc in larger projects. It is actively maintained and got a lot of traction. Software projects like Fedora or Couchbase migrated successfully. If you want to say hi, you can talk to Bonnie (gromit) and Ronny (indigo) in the Write the Docs channel in our Mattermost.

Project Migration Status

  • :o: Horizon/Meridian (@Bonrob, @indigo)
    • :building_construction: Installation Guide [:woman_technologist: jira/NMS-12497]
      • :white_check_mark: Horizon/Minion using gRPC (@indigo)
      • :white_check_mark: Time series storage with RRDTool
      • :white_check_mark: Time series storage with Newts
      • :white_check_mark: Install different versions than stable
      • :white_check_mark: Tuning Kafka (@indigo)
      • :o: Rebuild overview for Core
      • :o: Rebuild overview for Minion
      • :o: Rebuild overview for Sentinel
    • :building_construction: Administration Guide
      • :white_check_mark: About this Guide (removed as no longer required)
      • :o: Software overview (to be written)
      • :white_check_mark: Data Choices (Bonnie)
      • :white_check_mark: Users (Bonnie)
      • :white_check_mark: Provisioning (Bonnie)
      • :white_check_mark: Service Assurance (Bonnie)
      • :white_check_mark: Performance Management (Bonnie)
      • :white_check_mark: Thresholding (Bonnie)
      • :white_check_mark: Web UI (Bonnie) may remove this in final version
      • :white_check_mark: Events (Bonnie)
      • :white_check_mark: Alarms (Bonnie)
      • :white_check_mark: Notifications (Bonnie)
      • :white_check_mark: Business Service Monitoring (Bonnie)
      • :white_check_mark: Toplogy Map (Bonnie)
      • :white_check_mark: Asset Toplology Provider (Bonnie)
      • :white_check_mark: Database Reports (Bonnie)
      • :white_check_mark: Enhanced Linkd (Bonnie)
      • :white_check_mark: Open Tracing (@indigo)
      • :white_check_mark: Operation (Bonnie)
      • :white_check_mark: System Properties (Bonnie)
      • :white_check_mark: Ticketing (Bonnie)
      • :white_check_mark: Enabling RMI (Bonnie)
      • :white_check_mark: Minion (@indigo)
      • :white_check_mark: Sentinel (@indigo)
      • :white_check_mark: Special Cases and Workarounds (Bonnie)
      • :white_check_mark: IFTTT Integration (Bonnie)
      • :white_check_mark: DNS Resolver (Bonnie)
      • :white_check_mark: Telemetry Daemon (Bonnie)
      • :white_check_mark: Elasticsearch Integration (Bonnie)
      • :white_check_mark: Flow support (Bonnie)
      • :white_check_mark: Kafka Producer (Bonnie)
      • :white_check_mark: Alarm Correlation (Bonnie)
      • :white_check_mark: Meta-Data (Bonnie)
      • :white_check_mark: SNMP Interface Poller (Bonnie)
      • :white_check_mark: Administration (Bonnie)
  • :white_check_mark: Development Guide
    • :white_check_mark: Set up a Development System (Bonnie)
    • :white_check_mark: Minion Development (Bonnie)
    • :white_check_mark: Topology (Bonnie)
    • :white_check_mark: Graph Service API (Bonnie)
    • :white_check_mark: CORS Support (Bonnie)
    • :white_check_mark:REST API (Bonnie)
    • :white_check_mark: Develop Documentation (Bonnie - needs to be massively revised)
    • :white_check_mark: AMQP Integration (Bonnie)
    • :white_check_mark: Design and Style Guidelines (Bonnie)
  • :white_check_mark: Helm
  • :white_check_mark: ALEC
  • :white_check_mark: PRIS
  • :white_check_mark: OpenNMS.JS (@RangerRick)

Deliverables

The project is managed in our JIRA in Epic NMS-12497. We follow the “develop” branch which is currently targeting Horizon 28.0.0-SNAPSHOT.
Everything which is pushed to the working branches is pushed nightly with CircleCI to docs.opennms.com.

If you are impatient and you want to trigger the build + publish job immediately you need an account to access the CircleCI build job and click [ Rerun workflow from start ] on the “nightly” build.

How to Contribute

The branch jira/NMS-12497 represents the whole epic migrating everything to Antora. We follow develop 28.0.0-SNAPSHOT.

Step 1: Create an issue (Story) with the topic you want to work on from above. Assign your story to the epic NMS-12497.

Step 2: Create a branch based on jira/NMS-12497 and do some work

Step 3: Give us a Pull Request against the jira/NMS-12497 branch for review and merge

1 Like

:microphone: I got some feedback from reviewers and also tried to migrate the guides related to Docker

  • The Minion / Horizon descriptions to run with Docker are migrated and also updated to reflect the latest changes, especially configuring with confd.
  • In Horizon it is useful having the R-core packages installed to have forecasting and trending. It is now part of the Horizon install guide instead of a dedicated section.
  • I’ve changed the order for the tabs for the operating systems. The first one is also selected as default and used our most recommended one which is as of writing this CentOS/RHEL 8.
  • The corresponding articles are deleted in the TODO section

@Bonrob Digging further through the to-do list migrating the installation guide, I have decided to migrate the troubleshooting instructions for the Minion to a Knowledgebase Article in Troubleshooting Minion connectivity and functions. The information we had in the docs where extremely generic and I think we can have more life here instead of maintaining this article through the release cycles of Horizon/ Meridian. There is plenty of space to add more information than we had provided in our docs.

That makes a lot of sense.

I’ve migrated the installation instructions for Horizon/Minions using gRPC and gRPC with TLS. To verify if it’s working I’ve added a non-TLS version to our stack-play repository.

We decided to gather “tuning instructions” under “System Scalability”. We decide later if we have to rewrite them in a way to focus on the OpenNMS components and provide a hand off to Kafka/Cassandra/PostgreSQL/{other-tech-in-stack}

@Bonrob I’ve finished the migration for the Time Series Storage" sections and put them into the “System Scalability” bucket for now. I guess we need for the structure and wording some iteration once we finished the migration :slight_smile:

1 Like

@Bonrob I have migrated the How to install different versions than latest stable article to Discourse as well. I’ve noticed it doesn’t work anymore as we restructured our package repositories. The behavior between APT (Debian/Ubuntu) repositories and RPM (CentOS/RHEL) repositories are different. I have to talk with Ben what’s the right way to address this topic.

@Bonrob I’ll pick Sentinel and Minion next. There is some overlap with the install guide. I try to resolve it while migrating.