= 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:
== How do you contribute?
. Fork the https://github.com/stargate/docs[stargate/docs] github repository.
. If you have previously cloned the repo, switch to the main branch and do a git pull to get the latest changes.
. Create a working branch in your fork with git checkout -b <working-branch>.
Use a branch with a description or issue number.
. Make your edits to the existing topics. Add your new topic to the appropriate location in the docs-src directory`.
. Update the appropriate navigation menu (nav.adoc) for your new topic.
. Create your pull request at https://github.com/stargate/docs/pulls[stargate/docs/pulls].
. 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:
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):
== Dependencies in package.json
There are some key dependencies for building the documentation with Antora.
@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.
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:
. https://help.github.com/en/github/authenticating-to-github/creating-a-personal-access-token-for-the-command-line#creating-a-token[Create a personal access token].
. https://help.github.com/en/actions/automating-your-workflow-with-github-actions/creating-and-using-encrypted-secrets#creating-encrypted-secrets[Add it to stargate/docs as a repo secret].
. Update the name of the secret in publish.yaml.
== Reporting bugs
File a https://github.com/stargate/docs/issues[GitHub issue].