Building Docs and Website

The Apache Isis website and documentation are written in Asciidoc, using Antora as a static website generator.

Prerequisites:

The prerequisites to install are:

Assuming you have installed the latest Node LTS, these can be installed using:

npm i -g @antora/cli @antora/site-generator-default asciidoctor-kroki

See the Antora docs for details.

We also generate some Asciidoc files dynamically from other source code. This requires:

Authoring

To create/update documentation, we strongly recommend:

Even if you don’t use IntelliJ as your primary IDE, it’s worth using it for writing documentation - there’s currently nothing as good as the Asciidoc plugin on any other editor platform, especially when it comes to writing Antora.

Build

The preview.sh script can be used to build the website, also calling the documentation tooling that automates documentation from code (the System Overview, large parts of the Reference Guide and the Configuration Guide).

Use preview.sh -h to view options. The lower case flags skip steps, while the upper case flags exclude all steps except those indicated:

  • preview.sh

    builds everything and serves up the site

  • preview.sh -AS

    runs only Antora generation and serves up the site

  • preview.sh -ekcdl

    does the same thing, by skipping the other 5 steps.

The script can be found at the root of this git repo.