This repo contains the source files for the Stargate documentation.

The docs are written in asciidoc and use Antora to generate the output.

The Stargate docs are organized into three Antora modules:

• The ROOT module, with general project infomation.

• A quickstart module, with basic documentation to get new users started.

• The developers-guide module with more extensive topics on all the features of Stargate.

Antora requires NodeJS, install it and then install the project dependencies:

The current development version of the docs are generated and published at https://stargate.github.io/docs/.

The .github/workflows/antora.yml GitHub action will generate and publish the development docs on pushes to the master branch. Development docs use the site-local.yaml Antora site configuration file.

The docs can be generated locally during development, to check work. To generate only the docs (faster if you don’t need to check the OpenAPI docs):

To generate the docs and OpenAPI docs:

Open build/site/index.html a web browser to view the output.

Pushing a tag starting with v will trigger the .github/workflows/publish.yaml action that generates the docs and publishes them to the stargate/website repo in the gh-pages branch. The output will be put in the docs directory. Live docs use the site-publish.yaml Anotra site configuration file.

The Deploy to GitHub Pages action uses a repo secret in order to push the changes to stargate/website. To use a different secret:

1. Create a personal access token.

2. Add it to stargate/docs as a repo secret.

3. Update the name of the secret in publish.yaml.

File a GitHub issue or let us know in our Google group.