Build the Documentation

This section describes how to build the OpenNMS docs locally. We recommend that you do this to test major changes, particularly if adding a lot of new content or making significant revisions to existing content.

Clone the docs repository

If you already know how to use Git, then this is going to sound very familiar:

  1. Install Git.

  2. Locate the OpenNMS repository that you want to write documentation for (for example, the core OpenNMS repository) and fork it.

  3. Use Git to clone the repository (the original or the fork, as appropriate) to your local system: git clone <repo URL>.

If the project that you are working on already has version branches, then you will want to set up local copies of those as well.

After you have cloned the repository to your local system, you can track its branches with the following command:

Git command to track repository changes
git checkout -b <local_branch_name> <remote_repo>/<remote_branch_name>

Install Antora

To install Antora, follow the instructions on the Antora website.

Build the docs

Transform the Antora repository into a documentation site using the make docs command. Antora creates an archive of the documentation in build/site.zip, and an extracted version in public/index.html. You can open the latter directly in your browser.

The generic path to a given version of the docs is as follows:

<docs_repo_dir>/build/site/<distro>/<branch_dir_name>

Run Antora in Docker

You can also build the docs using a containerized version of Antora. To do so, run the following command in the repository’s root folder:

Console command to generate antora-playbook-local.yml file
docker run --rm -v $(pwd):/antora opennms/antora:2.3.4-b6293 --stacktrace generate antora-playbook-local.yml
You must have Docker installed to build the docs using this method.