NMS-13870: Add Nephron documentation

.circleci/config.yml

@@ -1,5 +1,9 @@
 version: 2.1
 
+executors:
+  docs-executor:
+    docker:
+      - image: antora/antora:2.3.4
 jobs:
   build:
     machine:
@@ -93,12 +97,33 @@ jobs:
           command: |
             mvn -s .circleci.settings.xml -DskipTests deploy
 
+  build-docs:
+    executor: docs-executor
+    steps:
+      - checkout
+      - run:
+          name: Install Antora LUNR site generator
+          command: |
+            npm i -g antora-site-generator-lunr
+      - run:
+          name: Generate HTML output for documentation
+          command: |
+            DOCSEARCH_INDEX_VERSION=latest DOCSEARCH_ENABLED=true DOCSEARCH_ENGINE=lunr NODE_PATH="$(npm -g root)" node --optimize-for-size $(which antora) --generator antora-site-generator-lunr --stacktrace generate antora-playbook-local.yml
+      - store_artifacts:
+          path: build/site.zip
+          destination: site.zip
+      - persist_to_workspace:
+          root: ~/
+          paths:
+            - project/public
+            - project/build
 
 workflows:
   version: 2
   build-deploy:
     jobs:
       - build
+      - build-docs
       - deploy:
           context: OSSRH Principal
           requires:

.gitignore

@@ -30,3 +30,6 @@ java/bin/
 .jqwik-database
 *.log
 
+# Antora documentation
+/build/
+/public/

Makefile

@@ -0,0 +1,73 @@
+##
+# Makefile to build OpenNMS docs
+##
+.PHONY: help docs docs-docker docs-deps docs-deps-docker docs-serve docs-serve-stop docs-clean docs-clean-cache clean-all
+
+.DEFAULT_GOAL := docs
+
+SHELL                := /bin/bash -o nounset -o pipefail -o errexit
+WORKING_DIRECTORY    := $(shell pwd)
+DOCKER_ANTORA_IMAGE  := opennms/antora:2.3.4-b6293
+SITE_FILE            := antora-playbook-local.yml
+
+help:
+	@echo ""
+	@echo "Makefile to build artifacts for OpenNMS"
+	@echo ""
+	@echo "Requirements to build the docs:"
+	@echo "  * Native: Antora installed globally with antora binary in the search path"
+	@echo "  * Docker: Docker installed with access to the official antora/antora image on DockerHub"
+	@echo ""
+	@echo "Targets:"
+	@echo "  help:             Show this help"
+	@echo "  docs-deps:        Test requirements to run Antora from the local system"
+	@echo "  docs-deps-docker: Test requirements to run Antora with Docker"
+	@echo "  docs:             Build Antora docs with a local install Antora, default target"
+	@echo "  docs-docker:      Build Antora docs with from Docker"
+	@echo "  docs-clean:       Clean all build artifacts in build and public directory"
+	@echo "  docs-clean-cache: Clear git repository cache and UI components from .cache directory"
+	@echo "  clean-all:        Clean build artifacts and Antora cache"
+	@echo "  docs-serve:       Run a local web server with Docker and Nginx to serve the docs locally"
+	@echo "  docs-serve-stop:  Stop the local web server for serving the docs"
+	@echo ""
+	@echo "Arguments: "
+	@echo "  DOCKER_ANTORA_IMAGE: Antora Docker image to build the documentation, default: $(DOCKER_ANTORA_IMAGE)"
+	@echo "  SITE_FILE:           Antora site.yml file to build the site"
+	@echo ""
+	@echo "Example: "
+	@echo "  make DOCKER_ANTORA_IMAGE=antora/antora:latest with-docker"
+	@echo ""
+
+deps-docs:
+	@command -v antora
+
+deps-docs-docker:
+	@command -v docker
+
+docs: deps-docs
+	@echo "Build Antora docs..."
+	antora --stacktrace $(SITE_FILE)
+
+docs-docker: deps-docs-docker
+	@echo "Build Antora docs with docker ..."
+	docker run --rm -v $(WORKING_DIRECTORY):/antora $(DOCKER_ANTORA_IMAGE) --stacktrace generate $(SITE_FILE)
+
+docs-clean:
+	@echo "Delete build and public artifacts ..."
+	@rm -rf build public
+
+docs-clean-cache:
+	@echo "Clean Antora cache for git repositories and UI components ..."
+	@rm -rf .cache
+
+clean-all: docs-clean docs-clean-cache
+
+docs-serve:
+	@echo "Start Nginx with public folder as html root ..."
+	docker run --rm -v $(WORKING_DIRECTORY)/public:/usr/share/nginx/html --name opennms-docs -p 8080:80 -d nginx
+
+docs-serve-stop:
+	@echo "Stopping Nginx docs server ..."
+	docker stop opennms-docs
+
+clean-all: docs-clean docs-clean-cache

antora-playbook-local.yml

@@ -0,0 +1,22 @@
+site:
+  title: Nephron Documentation
+  url: https://docs.opennms.com/nephron/
+  start_page: nephron::index.adoc
+content:
+  sources:
+    - url: .
+      branches: HEAD
+      start_path: docs
+ui:
+  bundle:
+    url: https://github.com/opennms-forge/antora-ui-opennms/releases/download/v2.0.6/ui-bundle.zip
+  supplemental_files: ./docs/supplemental-ui
+asciidoc:
+  attributes:
+    stem: latexmath
+output:
+  clean: true
+  dir: ./public
+  destinations:
+    - provider: fs
+    - provider: archive

docs/antora.yml

@@ -0,0 +1,14 @@
+name: nephron
+version: '0.3.1-SNAPSHOT'
+title: Nephron
+prerelease: true
+asciidoc:
+  attributes:
+    experimental: true
+    prerelease: true
+    source-language: asciidoc@
+    xrefstyle: short@
+    compatible-horizon: '26.1.0-SNAPSHOT'
+    compatible-meridian: '2020.x'
+nav:
+  - modules/ROOT/index.adoc

docs/modules/ROOT/pages/index.adoc

@@ -0,0 +1,10 @@
+[[welcome]]
+= Welcome to the {page-component-title} Documentation
+
+[options="autowidth"]
+|===
+|Version:     |{page-component-display-version}
+|Last update: |{docdatetime}
+|===
+
+OpenNMS {page-component-title} is an open source streaming analytics tool for network flows.

docs/supplemental-ui/css/admonition-labels.css

@@ -0,0 +1,32 @@
+.doc .admonitionblock .icon {
+  border-radius: 1rem;
+}
+
+i.fa[class^='icon-'],
+i.fa[class*=' icon-']::before {
+  content: "";
+  height: 1.25rem;
+  width: 1.25rem;
+  margin-right: 0.25rem;
+  margin-left: -0.5rem;
+}
+
+i.fa.icon-note::before {
+  background: no-repeat url("../img/note.svg");
+}
+
+i.fa.icon-tip::before {
+  background: no-repeat url("../img/tip.svg");
+}
+
+i.fa.icon-important::before {
+  background: no-repeat url("../img/important.svg");
+}
+
+i.fa.icon-warning::before {
+  background: no-repeat url("../img/warning.svg");
+}
+
+i.fa.icon-caution::before {
+  background: no-repeat url("../img/caution.svg");
+}

docs/supplemental-ui/css/search.css

@@ -0,0 +1,115 @@
+.navbar-brand .navbar-item + .navbar-item {
+  flex-grow: 1;
+  justify-content: flex-end;
+}
+
+@media screen and (min-width: 1024px) {
+  .navbar-brand {
+    flex-grow: 1;
+  }
+
+  .navbar-menu {
+    flex-grow: 0;
+  }
+}
+
+#search-input {
+  color: #333;
+  font-family: inherit;
+  font-size: 0.95rem;
+  width: 150px;
+  border: 1px solid #dbdbdb;
+  border-radius: 0.1em;
+  line-height: 1.5;
+  padding: 0 0.25em;
+}
+
+@media screen and (min-width: 769px) {
+  #search-input {
+    width: 200px;
+  }
+}
+
+.search-result-dropdown-menu {
+  position: absolute;
+  z-index: 100;
+  display: block;
+  right: 0;
+  left: inherit;
+  top: 100%;
+  border-radius: 4px;
+  margin: 6px 0 0;
+  padding: 0;
+  text-align: left;
+  height: auto;
+  background: transparent;
+  border: none;
+  max-width: 600px;
+  min-width: 500px;
+  box-shadow: 0 1px 0 0 rgba(0, 0, 0, 0.2), 0 2px 3px 0 rgba(0, 0, 0, 0.1);
+}
+
+@media screen and (max-width: 768px) {
+  .navbar-brand .navbar-item + .navbar-item {
+    padding-left: 0;
+    padding-right: 0;
+  }
+
+  .search-result-dropdown-menu {
+    min-width: calc(100vw - 3.75rem);
+  }
+}
+
+.search-result-dataset {
+  position: relative;
+  border: 1px solid #d9d9d9;
+  background: #fff;
+  border-radius: 4px;
+  overflow: auto;
+  padding: 0 8px 8px;
+  max-height: calc(100vh - 5.25rem);
+  color: #333;
+}
+
+.search-result-highlight {
+  color: #174d8c;
+  background: rgba(143, 187, 237, 0.1);
+  padding: .1em .05em;
+}
+
+.search-result-item {
+  display: flex;
+  font-size: 1rem;
+  margin-bottom: 0.5rem;
+  margin-top: 0.5rem;
+}
+
+.search-result-document-title {
+  width: 33%;
+  border-right: 1px solid #ddd;
+  color: #a4a7ae;
+  font-size: 0.8rem;
+  padding: 0.25rem 0.5rem 0.25rem 0;
+  text-align: right;
+  position: relative;
+  word-wrap: break-word;
+}
+
+.search-result-document-hit {
+  flex: 1;
+  font-size: 0.75em;
+  color: #02060c;
+  font-weight: 700;
+}
+
+.search-result-document-hit > a {
+  color: inherit;
+  display: block;
+  padding: 0.5rem 0 0.5rem 1rem;
+  margin-bottom: 0.25rem;
+}
+
+.search-result-document-hit > a:hover {
+  background-color: rgba(69, 142, 225, 0.05);
+}
+