Stargate documentation

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.

Dependencies

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

npm install

Viewing the current HTML output

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.

Generating and viewing the HTML output locally

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):

npm run build:local

To generate the docs and OpenAPI docs:

npm run build:dev

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

Publishing to the Stargate website

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.

Reporting bugs

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