DataStax Astra CLI Documentation

This repo contains the documentation source files for the DataStax Astra CLI documentation.

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

Table of Contents

Contributing to the docs
Working with Astra CLI docs
- Submitting your changes
Generating and viewing the HTML output locally
Repo dependencies
- Dependencies in package.json

Contributing to the docs

Although this repo is maintained by the DataStax Docs team, contributions from the community are gratefully accepted, and encouraged.

Why should you contribute to the Astra CLI docs?

It makes the Docs team’s job easier.
It makes your job easier.
It helps DataStax and Cassandra users more quickly.

How do you contribute?

The majority of DataStax documentation source files are written in AsciiDoc, a lightweight, human-readable markup language. You can contribute to the documentation by adding content to, or editing, the AsciiDoc files in this repo.

For instructions, see Working with Astra CLI docs below.

Working with Astra CLI docs

Before following the steps below, first make sure that you have git installed on your computer.

Using a terminal, clone the astra-cli-docs repository (this repository) onto your computer.
```
git clone https://github.com/datastax/astra-cli-docs.git
```
cd into the cloned repo.
```
cd astra-cli-docs
```
If you have previously cloned the repo, switch to the main branch and do a git pull to get the latest changes.
```
git checkout main && git pull
```
Create a working branch.
```
git checkout -b <working-branch>
```
Replace <working-branch> with a descriptive name or a related JIRA ticket number.
Locate the .adoc file that you wish to edit and open it in your preferred editor (.adoc files are stored in the docs-src directory). Make sure to save your changes once you’re done making edits.

If adding a new page, make sure to add it to the appropriate location in the docs-src directory and then update the appropriate navigation file (nav.adoc) so that the new page will show up in the left-hand navigation of the docs website.
Preview your changes by running a local build.

Commit your changes.

git commit -m "<description-of-changes>"

Push your changes to GitHub.
```
git push -u origin <working-branch>
```

Submitting your changes

Once all of your changes are pushed to GitHub, you’ll need to submit them for review by creating a pull request.

Create your pull request against the main[main] branch.
Assign someone from the docs team as a reviewer.
- @jgillenwater
- @polandll

The docs team will review, ask questions, make requests, and merge your changes. The docs team will then update the published documentation to reflect your changes.

For more information on contributing to the docs, click here.

Generating and viewing the HTML output locally

You can generate the HTML docs locally to view changes and check your work. Note that these steps assume you’ve already cloned the astra-cli-docs repo and checked out the main branch (see Working with Astra CLI docs for more information).

Using a terminal, cd into the cloned repo directory and run the following command:

./build-locally.sh astra-cli

Important

Dependencies

The build-locally.sh script requires nvm to be installed on your system in order to install and update the rest of the required dependencies. If you’re running macOS and have Homebrew installed, the script will automatically install nvm for you. If you’re running on another platform (or don’t use Homebrew), you’ll need to manually install nvm before running the above command.

If the docs built successfully, you’ll see output similar to the following:

Site generation complete!
Open file:///Users/your-user-name/astra-cli-docs/build/astra-cli in a browser to view your site.

Do you want to start a local web server for viewing the generated docs? (Y or N)

The build-locally.sh script prints the local file path of the generated docs, and prompts you about starting a local web server for viewing the docs. Since the generated docs HTML files can be viewed directly in a web browser without the need for a web server, most users should answer N to the prompt. (The web server is only required for viewing certain advanced functionality of the site build.)

To view the generated HTML files directly (most users)

Copy the entire file: path from the terminal output, and open it in a web browser.
In the file browser, click docs, then click on any of the .html files.
From here, you can browse the documentation just like you would on docs.datastax.com.
If you end up making further edits to the documentation, simply run the build-locally.sh script again to view your latest changes.

To view the docs using the local web server (advanced users)

When prompted to start the local web server, type Y and press Return.

When the web server starts up, you’ll see output similar to the following:

   ┌────────────────────────────────────────────────────┐
   │                                                    │
   │   Serving!                                         │
   │                                                    │
   │   - Local:            http://localhost:3000        │
   │   - On Your Network:  http://192.168.86.141:3000   │
   │                                                    │
   │   Copied local address to clipboard!               │
   │                                                    │
   └────────────────────────────────────────────────────┘

Copy the Local: address (in this case, http://localhost:3000) and open it in a web browser.
From the Index of astra-cli-docs/ page, click build/ > astra-cli/ > docs/
From here, you can browse the documentation just like you would on docs.datastax.com.
Once you’re done viewing the documentation, go back to your terminal window and press Ctrl+C to shut down the web server.
If you end up making further edits to the documentation, simply run the build-locally.sh script again to view your latest changes.

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

brew install node

npm install

Dependencies in package.json

There are some key dependencies for building the DataStax documentation.

  "dependencies": {
    "@antora/cli": "~3.0.1",
    "@antora/site-generator-default": "~3.0.1",
    "linkinator": "~3.0.3",
    "async": "~3.2.4",
    "mobx": "~6.0.4",
    "react": "~16.8.4",
    "react-dom": "~16.8.4",
    "rxjs": "~7.0.1",
    "styled-components": "~5.1.1"
  }

@antora/cli and @antora/site-generator-default are requirements to build with Antora.

datastax / astra-cli-docs