feat(docs): create Antora documentation

.circleci/config.yml

@@ -22,3 +22,6 @@ jobs:
       - run:
           name: Run tests
           command: npm --prefer-offline --no-progress run dist-test
+      - run:
+          name: Build documentation
+          command: npm --prefer-offline --no-progress run docs

.gitignore

@@ -40,3 +40,7 @@ grafana
 dist/cli.*
 dist/opennms.*
 dist/docs
+
+# Antora documentation
+docs/
+build/

README.md

@@ -2,51 +2,35 @@
 
 A client API for accessing the OpenNMS network monitoring platform.
 
-# Using the OpenNMS.js APIs In Your Code
+## Using the OpenNMS.js APIs In Your Code
 
-Information on getting started and how to use the API is in the [HOWTO document](https://github.com/OpenNMS/opennms-js/blob/master/HOWTO.md).
+Information on getting started and how to use the API is in the [OpenNMS Documentation](https://docs.opennms.com/).
 
-The complete API list is available at [docs.opennms.org](http://docs.opennms.org/opennms-js/branches/master/opennms-js/opennms-js.html).
+The complete API list is available at [opennms.github.io](https://opennms.github.io/opennms-js/).
 
-# Using the OpenNMS.js Command Line
+## Using the OpenNMS.js Command Line
 
 1. install [Node.js](https://nodejs.org/en/download/)
-2. run `sudo npm install -g opennms`
-3. run `opennms --help` for a list of possible commands
+2. run `npm install -g opennms`
+3. run `opennms --help` for a list of available commands
 
-# API Coverage
-
-OpenNMS.js currently supports a subset of the OpenNMS ReST API:
-
-* query alarms, events, and nodes (including complex queries against OpenNMS Horizon 21+ and Meridian 2017+)
-* acknowledge, escalate, and clear alarms
-* create, update, and close trouble tickets against an alarm
-* create, update, and delete alarm sticky memos
-* create, update, and delete alarm journal memos
-
-Future plans include adding support for other common ReST operations:
-
-* creating, updating, deleting, and importing requisitions
-* query the measurements ReST API (RRD/Newts time-series data)
-* query outages and notifications
-
-# Changes and Versioning
+## Changes and Versioning
 
 The CHANGELOG should always contain the complete list of changes between versions, and should always be accessible [here](https://github.com/OpenNMS/opennms-js/blob/master/CHANGELOG.md).
 
 OpenNMS.js follows [semantic versioning](https://semver.org/).
 
-## Release Notes
+### Release Notes
 
-### 2.0.1
+#### 2.0.1
 
 This is a small release with some dependency updates and a fix for handling of ReST data that is missing a response.
 
-### 2.0.0
+#### 2.0.0
 
 OpenNMS.js 2.0 adds a few new APIs, contains a ton of refactoring and build system updates, and has a few small breaking changes.
 
-#### Notable Changes:
+##### Notable Changes
 
 * updated CLI libraries to fix/improve table output
 * better, faster build system to improve generated code
@@ -57,7 +41,7 @@ OpenNMS.js 2.0 adds a few new APIs, contains a ton of refactoring and build syst
 * filter API now supports `orderBy` and `order` (and the `alarms` CLI list command supports it)
 * HTTP parameters in `OnmsHTTPOptions` can now have multiple values -- for example a parameter with value `[ 1, 2 ]` will serialize to `&foo=1&foo=2`
 
-#### Breaking Changes:
+##### Breaking Changes
 
 * The `api/Log` module now only exports a single, simplified `log` object; `typescript-logging` was overly complicated and not really adding much in the way of value.  Use `.setDebug()`, `.setQuiet()`, and `.setSilent()` to change the logging level instead.
 * A number of the TypeScript APIs have been clarified to be explicitly nullable (and/or `undefined`-able) to make strict null- and type-checking validation pass.
@@ -68,28 +52,28 @@ OpenNMS.js 2.0 adds a few new APIs, contains a ton of refactoring and build syst
   The `OnmsHTTPOptions` and `OnmsServer` objects now have builders (use `.newBuilder()` to create) rather than constructors with a bunch of arguments.
 * The `id` property on `OnmsServer` is no longer generated, it is computed based on the contents of the server object and should be repeatably equal if the contents are equal.
 
-### 1.5
+#### 1.5
 
 This release includes support for some additional flow queries, as well as a few security updates and a fix for CLI formatting.
 
-### 1.4
+#### 1.4
 
 This is a small feature release with a few changes targeted primarily to Helm (adding root cause and tags to the situation feedback API support, and support for `isAcknowledged` queries on alarms).
 
-### 1.3
+#### 1.3
 
 This release contains a number of new features and a few bug fixes, including support for correlation alarms and feedback, and additional metadata for Helm 3.
 
-### 1.2
+#### 1.2
 
 This is a small release which adds support for a default timeout in `GrafanaHTTP`, as well as adding `X-Requested-With` headers to requests ([NMS-9783](https://issues.opennms.org/browse/NMS-9783)).
 
-### 1.1
+#### 1.1
 
 This release adds support for telemetry (Netflow) APIs which will be introduced in OpenNMS 22.x.
 It also includes a number of build optimizations and updates since 1.0.
 
-### 1.0
+#### 1.0
 
 The initial official release of OpenNMS.js.
 
@@ -101,30 +85,3 @@ OpenNMS.js currently supports a subset of the OpenNMS ReST API:
 * create, update, and delete alarm sticky memos
 * create, update, and delete alarm journal memos
 
-
-# Development
-
-To build this project, first use `npm` to fetch all dependencies:
-
-`npm install`
-
-Then you can use `npm run` to build or test the project:
-
-* `npm run dist` - run tests and lint, and build the complete tree in `dist/`
-* `npm run dev` - build a development version of the API in `dist/opennms.js` and `dist/opennms.node.js`
-* `npm run build` - build the development and production versions of the API in `dist/`
-* `npm run docs` - build the docs in `dist/docs/`
-* `npm run watch` - continuously build the development version in `dist/opennms.js`
-* `npm run test` - run the tests
-* `npm run watch-test` - continuously run the tests
-* `npm run cli -- <arguments>` - run the CLI test tool (try `--help` for options)
-
-# Reporting Bugs or Feature Requests
-
-OpenNMS.js issues are tracked in the OpenNMS issue tracker: https://issues.opennms.org/browse/JS
-
-# Debugging Tests
-
-On MAC OS X with WebStorm v2017.2 debugging tests may not work.
-See https://github.com/facebook/jest/issues/1652 for more details.
-The described solution there is to add `--env jest-environment-node-debug` as argument to the runtime configuration.

docs-src/antora.yml

@@ -0,0 +1,5 @@
+name: opennms-js
+version: '2.0.3-SNAPSHOT'
+title: OpenNMS.js
+nav:
+  - modules/ROOT/nav.adoc

docs-src/modules/ROOT/nav.adoc

@@ -0,0 +1,14 @@
+.About
+* xref:about:introduction.adoc[What is OpenNMS.js?]
+* xref:about:legal_notice.adoc[Legal Notice]
+
+.Installation
+* xref:installation:cli.adoc[CLI Utility]
+* xref:installation:js.adoc[JavaScript/TypeScript API]
+
+.Contributing
+* xref:contributing:index.adoc[Contributing]
+
+.Using
+* xref:using:developing.adoc[Developing]
+* xref:using:api-basics.adoc[API Basics]

docs-src/modules/ROOT/pages/index.adoc

@@ -0,0 +1,21 @@
+
+:imagesdir: ../assets/images
+
+[[welcome-index]]
+= {page-component-title} {page-version} Documentation
+
+:data-uri:
+:icons:
+
+[.lead]
+Welcome to the {page-component-title} {page-version} documentation: information and guides to help you learn about {page-component-title} and start exploring its features.
+
+[TIP]
+====
+Use the left navigation bar to browse the documentation or the links below to access some highlights.
+====
+
+[big]*Need help?*
+
+* talk to us in https://chat.opennms.com/opennms/channels/opennms-development[chat]
+* join our community on https://opennms.discourse.group/latest[Discourse]

docs-src/modules/about/pages/introduction.adoc

@@ -0,0 +1,17 @@
+:imagesdir: ../assets/images
+:!figure-caption:
+
+= What is {page-component-title}?
+
+{page-component-title} is both a command-line utility as well as a collection of JavaScript and TypeScript APIs for interacting with OpenNMS Horizon and Meridian servers.
+
+[[cli]]
+== Command-Line Utility
+
+The CLI is a tool for performing a variety of operations against an OpenNMS server, most notably querying, acknowledging, and creating tickets from alarms.
+
+[[api]]
+== JavaScript and TypeScript API
+
+The JavaScript and TypeScript API provides access to a wide variety of functions for interacting with an OpenNMS server.
+It provides a core of functionality used by other OpenNMS tools, most notably Helm.

docs-src/modules/about/pages/legal_notice.adoc

@@ -0,0 +1,13 @@
+[[welcome-legal-notice]]
+= Legal Notice
+{}
+{page-version}
+:data-uri:
+:icons:
+
+[.lead]
+Copyright © {docyear} The OpenNMS Group, Inc.
+
+OpenNMS is a registered trademark of The OpenNMS Group, Inc.
+
+All other trademarks are the property of their respective owners.

docs-src/modules/contributing/pages/index.adoc

@@ -0,0 +1,4 @@
+# Contributing
+
+* Fork me on https://github.com/OpenNMS/opennms-js[GitHub]
+* Open an https://issues.opennms.org/projects/JS/summary[issue in JIRA]

docs-src/modules/installation/pages/cli.adoc

@@ -0,0 +1,22 @@
+= Getting Started With the CLI Utility
+
+== Installation
+
+Just install the `opennms` project globally, using https://www.npmjs.com/[npm].
+
+1. install https://nodejs.org/en/download/[Node.js] (Node.js comes with `npm`)
+2. run `npm install -g opennms`
+3. run `opennms --help` for a list of available commands
+
+== Configuration
+
+Before you can query your OpenNMS server, you must first configure the command-line tool to know where to find it.
+
+Run:
+
+[source, shell]
+----
+opennms connect --username <your-username> --password <your-password> https://your-opennms-server/opennms
+----
+
+This will store a configuration file that the `opennms` command will read automatically when you run it.

docs-src/modules/installation/pages/js.adoc

@@ -0,0 +1,11 @@
+= Getting Started With the JavaScript or TypeScript API
+
+== Installation
+
+You can use NPM or Yarn to install `opennms` as a dependency to your project`
+
+```bash
+npm install opennms
+# or
+yarn install opennms
+```

docs-src/modules/using/pages/api-basics.adoc

@@ -0,0 +1,72 @@
+= OpenNMS.js API Basics
+
+== Importing the Code
+
+=== TypeScript
+
+If you are using TypeScript, you can import the APIs directly into your project:
+
+[source,javascript]
+----
+import { API, Model, Rest, DAO, Client } from 'opennms/src/API';
+----
+
+=== JavaScript
+
+[source,javascript]
+----
+const { API, Model, Rest, DAO, Client } = require('opennms');
+----
+
+== Connecting to a Server
+
+Before you can make any queries, you must first connect to a server.
+To do so, use the `Client` object.
+
+[source,javascript]
+----
+const client = await new Client().connect('Demo', 'http://my-server:8980/opennms/', 'admin', 'admin');
+----
+
+== Making Queries
+
+To make a query, OpenNMS.js provides a number of DAO APIs for accessing data through ReST.
+
+To do so, you first connect (like above), and then call into the appropriate DAO to query.
+
+Here's an example that queries alarms with an ID greater than 7:
+
+[source,javascript]
+----
+const { Comparators, Filter, Restriction } = API;
+const idRestriction = new Restriction('id', Comparators.GE, 7);
+const filter = new Filter().withOrRestriction(idRestriction);
+
+try {
+  const alarms = await client.alarms().find(filter);
+  console.info(`got ${alarms.length} alarms with id >= 7.`);
+
+  // get all the node IDs associated with the matching alarms
+  const allNodeIds = alarms
+    .map((alarm) => alarm.nodeId)
+    .filter((nodeId) => nodeId !== undefined);
+
+  // create a unique list
+  const nodeIds = allNodeIds
+    .filter((val,index) => allNodeIds.indexOf(val) === index);
+
+  // if the 2nd argument to nodes().get() is true,
+  // it also populates ipInterfaces and snmpInterfaces
+  const nodes = await Promise.all(
+    nodeIds.map(id => client.nodes().get(id, true))
+  );
+
+  nodes.forEach(node => {
+    const numIfaces = node.ipInterfaces.length;
+    console.info(`${node.id} (${node.label}) has ${numIfaces} IP interfaces.`);
+  });
+----
+
+== API Reference
+
+The complete API reference is available at https://opennms.github.io/opennms-js/

docs-src/modules/using/pages/developing.adoc

@@ -0,0 +1,32 @@
+= Using OpenNMS.js
+
+== Development and Production Branches
+
+Development is done in the `develop` (default GitHub) branch.
+
+Commits to the `develop` branch are automatically compiled and committed to the `master` branch.
+
+Releases are tagged from the `master` branch and submitted to https://www.npmjs.com/package/opennms[npm].
+
+== Working With the Project Code
+
+First, you must install the project dependencies.
+You can do so with `npm`:
+
+```bash
+npm install
+```
+
+[[commands]]
+Then, there are a number of commands you can run to work with the code:
+
+`npm run dev`:: build the non-minified, development version of the code into the `dist/` directory
+`npm run build`:: build both the development and production versions of the code into the `dist/` directory
+`npm run test`:: run the unit tests
+`npm run lint`:: check the TypeScript code for errors and formatting warnings
+`npm run docs`:: build the API documentation into the `dist/docs/` directory
+`npm run changelog`:: generate the `CHANGELOG.md` file from the current git history
+`npm run watch`:: build the development version of the code into the `dist/` directory, automatically re-compiling if code changes are detected
+`npm run watch-test`:: run the tests continuously, automatically re-running if code changes are detected
+`npm run dist`:: does everything necessary to update the `dist/` directory with the latest changes, including lint, test, build(s), and docs
+`npm run cli`:: run the CLI tool directly from the source tree (eg, `npm run cli -- connect -u admin -p admin http://your-opennms:8980/opennms/`)

local-site.yml

@@ -0,0 +1,21 @@
+site:
+  title: OpenNMS.js Documentation
+  url: https://docs.opennms.com/opennms-js/
+  start_page: opennms-js::index.adoc
+content:
+  sources:
+  - url: .
+    branches: HEAD
+    start_path: docs-src
+ui:
+  bundle:
+    url: https://github.com/opennms-forge/antora-ui-opennms/releases/download/v1.2.1/ui-bundle.zip
+asciidoc:
+  attributes:
+    stem: latexmath
+output:
+  clean: true
+  dir: ./public
+  destinations:
+  - provider: fs
+  - provider: archive