README.adoc

Stackable Documentation

This is the main repository for the documentation of the Stackable platform. Have a look at the live version and the current nightly live version.

The documentation is built with Antora. This repository hosts the Antora playbook file as well as platform documentation. Other Stackable repos contain docs directories which are pulled in by this repo.

Repository structure

• The antora.yml file defines the main home Component.

• The various *-playbook.yml files are Antora playbook files used to build the docs, either locally or for production. The playbooks link to all the other repositories that contain content.

• The modules directory contains the platform level documentation content.

Building locally

Dependencies: make, npm.

To build the site, pull submodules, install dependencies and run make:

$ git submodule update --init
$ npm ci
$ make

Note	Antora caches the external content repos in the cache directory (configured to be ./cache). It will not automatically update those. Use the --fetch flag (make ANTORAFLAGS=--fetch) to update all sources, or use make clean to delete the cache and build directory.

Production deployment

The documentation is deployed by Netlify on a regular basis or when something is pushed to the main branch. To trigger an out of band deployment, use the Build and deploy production site GitHub action (internal contributors only).

Regular (nightly) deployments are run to pick up changes in the operator repositories. These repositories are not watched by Netlify and thus any changes to the documentation there would be ignored.

Netlify configuration

Netlify is configured with the netlify.toml file inside of the documentation repo. In there, the command make netlify-build is configured as the build command. Further documentation of the build process can then be found in the Makefile.

The build process creates a static site in build/site which is then published (as it is configured in the netlify.toml).

Development

Generating the documentation

During development, it can be helpful to use a playbook local-antora-playbook.yml which uses content from the local directory instead of the remote git repository. The playbook used by the Makefile can be overridden using the PLAYBOOK variable (run make PLAYBOOK=my-local-playbook.yml).

content:
  sources:
  - url: ./
    branches: HEAD

Note	Antora does not recognize git submodules as git repositories

The design & layout comes from our UI repository.

LIVERELOAD=true gulp may be used to recreate the built documentation after each edit.

More useful links

• The documentation-ui repository.

• The crddocs repository from which the CRD reference is generated.

• The Stackable contributor’s guide containing more info on how to contribute to the documentation.