Skip to main content

About this manual

This manual is part of the source code. It lives in the site/ folder of the repository, is built with Docusaurus, and is published to git-pages by the continuous integration of the project. Each page describes the software at the commit that was built, so the manual cannot fall behind the interface.

What happens on each change​

On every change to the default branch, and on every merge request that touches the code, the interface or the manual, the pipeline:

  1. builds the web interface and the server from the same commit;
  2. starts the server with a real Redis and local storage, and fills it with demo data: two clusters, three agents, one viewer account, two CPE mappings, alert rules and a report;
  3. drives a headless browser through the pages, and captures each screenshot the manual uses;
  4. builds the manual with the screenshots, failing if any image is missing;
  5. publishes the manual to git-pages, on the default branch only.

Because the screenshots are captured again on every run, a change to the interface shows up in the manual on the next pipeline without anyone editing an image.

The demo data is written by site/screenshots/seed.mjs. The fixtures it uploads are the CycloneDX documents in site/screenshots/fixtures. The screenshots are taken by site/screenshots/capture.mjs, which lists each image with the page it shows.

Writing the manual​

  • Write pages as Markdown in site/docs. The folders are the three guides, User, Administrator and Reference; the sidebars are in site/sidebars.js.
  • Link to other pages with their address, such as /admin/hosts, so that the build checks the link. A broken link fails the build.
  • Reference a screenshot with a light and a dark version, one inside each screenshot-light and screenshot-dark div: ![Description](/img/screenshots/name-light.png) and ![Description](/img/screenshots/name-dark.png). The reader's theme picks one of them. To add one, add it to site/screenshots/capture.mjs first; the script takes both versions.
  • Keep the wording of the interface exactly as it appears: button labels, column names and tab names. The screenshots are the proof.
  • Put facts that change often, such as default values, in the environment reference and link to them from the guides.

Building it locally​

Node.js 20 or later and pnpm are needed.

make docs # install and build the manual into site/build
make docs-start # a live preview at http://localhost:3000
make docs-screenshots # captures the screenshots from a running server

make docs-screenshots needs a running server that has no data yet, because it creates the demo users, agents and rules. Set VOP_URL to its address and VOP_ADMIN_PASSWORD to the password of its administrator, and set CHROMIUM_PATH if no Chromium is installed for Playwright. Without screenshots the build still succeeds, with warnings for the missing images; the pipeline builds with DOCS_STRICT=1, which fails instead.

Versions​

The manual describes the version of the software in the commit it was built from. The pages are not versioned separately. If you run an older release, read the manual of that release in its repository, not the latest one.