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 two Antora components:

• stargate-core

  • ROOT module: general information pages, plus attachments

  • concepts module: how Stargate works

  • plan module: To be completed

  • install module: how to install Stargate

  • connect module: how to connect to Stargate

  • manage module: management information

  • secure module: how to secure Stargate

  • migrate module: To be completed

• stargate-develop

  • develop module: complete API documentation

  • quickstart module: basic documentation to get new users started

How do you contribute?

1. Fork the stargate/docs github repository.

2. If you have previously cloned the repo, switch to the main branch and do a git pull to get the latest changes.

3. Create a working branch in your fork with git checkout -b <working-branch>. Use a branch with a description or issue number.

4. Make your edits to the existing topics. Add your new topic to the appropriate location in the docs-src directory`.

5. Update the appropriate navigation menu (nav.adoc) for your new topic.

6. Create your pull request at stargate/docs/pulls.

7. Assign @polandll as a reviewer for quick turnaround.

Generating and viewing the HTML output locally

If you wish to build locally to check a docset build, use build-locally.sh.

There are two options (dev-stargate, stargate). One builds the API references in addition to the documentation. Run the command with:

./build-locally.sh stargate

The script will check for dependencies and install or update any software required for the build.

Open build/site/<docset>, such as build/site/stargate, in a web browser to view the output.

Repo Dependencies

The build-locally.sh script should take care of installations required to build the docs. However, if you get a message that you need to install NodeJS, run the following commands (Mac OSX):

brew install node
npm install

Dependencies in package.json

There are some key dependencies for building the documentation with Antora.

  "dependencies": {
    "@antora/cli": "^3.0.1",
    "@antora/site-generator-default": "^3.0.1",
    "@redocly/cli": "1.0.0-beta.102",
    "async": "3.2.4",
    "mobx": "^6.3.12",
    "react": "^16.8.4",
    "react-dom": "^16.8.4",
    "redoc": "^2.0.0-rc.70",
    "redoc-cli": "^0.13.14",
    "rxjs": "7.0.1",
    "styled-components": "^5.1.1"
  }

@antora/cli and @antora/site-generator-default are requirements to build with Antora. redoc and redoc-cli are requirements to build the 3-panel API references. @redocly/cli is a requirement for the OpenAPI linter that is used to validate the OpenAPI YAML specification files used to build the 3-panel API references.

Important

It has been reported that the GraphQL functionality will not work if node-fetch is greater than version 2.6.1. You will need to downgrade that package before building if you encounter errors.

Viewing the current published 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 main branch. Development docs use the playbooks/site-local-<docset>.yaml Antora site configuration file.

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 Antora 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.