Write and Build Documentation

If you want to contribute documentation to this project which manages the docs with Antora, you’ve come to the right place.

Installing Antora

Antora is a documenation site generator based around the AsciiDoc format. To install Antora, follow the instructions on the Antora website.

Making a Copy of the OpenNMS Docs Repo

If you already know how to use git, then this is going to sound very familiar. If not, here’s the full walk-through:

  1. Install git.

  2. If the docs source is hosted on GitHub, you will probably next need to fork the OpenNMS Helm repo.

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

If the project that you are working in already has version branches, then you will want to set up local copies of those as well. After you have cloned the repo to your local system, you can track those branches with the command:

$ git checkout -b <local_branch_name> <remote_repo>/<remote_branch_name>

Write the Docs

The documentation for the project lives in the docs directory within the source code repository you have checked out. Each main section is structured in directories and contain the text .adoc files. The text files need to be written in the AsciiDoc format.

Every new created directory or text file needs to be included in the general structure of the documentation. The nav.adoc file in the ROOT direcory defines the content hierarchy.

Structure of the nav.adoc file
.About  (1)
* xref:about:welcome.adoc[Welcome] (2)
* xref:about:legal_notice.adoc[Legal Notice]  (2)

.Installation  (3)
* xref:installation:requirements.adoc[Requirements]  (4)
* xref:installation:rpm.adoc[Installing on RPM-based Linux (CentOS, Fedora, OpenSuse, RedHat)]  (4)
* xref:installation:debian.adoc[Installing on Debian/Ubuntu]  (4)
1 Friendly directory name About which appears in the left navigation.
2 Each topic in the About section, written as a cross reference to the directory, file name, and friendly name that appears in the left navigation.
3 Second section Installation.
4 Each topic in the Installation section.

IF images needs to be included, use a directory assests/images inside each module folder. Within the text file images are included as the following:

// At the beginning of the .adoc text file
:imagesdir: ./images  (1)

.Overview of the structure of Helm  (2)
image::helm-diagram.svg[Helm Diagram, 600]  (3)
1 Lookup directory for images for this text file.
2 Description of the image.
3 Include the image with an alternative text and a proportional width of 600 pixels.

The _distro_map.yml controls the overall behavior of how docs are generated for different branches and distributions. It is normally not necessary to touch this file when just creating or changing existing content. The file is described as the following:

---
helm: (1)
  name: Helm
  author: OpenNMS Docs Team <opennms-docs@lists.sourceforge.net>
  site: opennms (2)
  site_name: OpenNMS
  site_url: https://docs.opennms.org/helm
  branches:
    master: (3)
      name: Latest (4)
      dir: latest (5)
1 System name of distro, used when conditionalizing content on a per-distro basis.
2 System name of site, used to pick up the correct index file and organize the included distros.
3 Git branch name that represents a version of this distro.
4 User-readable name of this version of this distro.
5 Directory on the site where this version of this distro should go.

Building the Docs

The documentation is located in the docs directory. Transforming an Antora repo into a documentation site is pretty easy:

antora generate local-site.yml

Build Output

Antora creates a .zip file of the documentation site in the build directory. Unzipping the file reveals the HTML content in the site directory.

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

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