Skip to content

Asciidoc How-to guide for use with several DataStax documentation guides. We use AsciiDoc for writing documentation, and want users to know how to contribute.

Notifications You must be signed in to change notification settings

datastax/adoc-howto

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

25 Commits
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

DataStax Docs Contributor’s Guide

This repo contains the documentation source files for the DataStax Docs Contributor’s Guide documentation.

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

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 Docs Contributor’s Guide 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 Docs Contributor’s Guide docs below.

Working with Docs Contributor’s Guide docs

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

  1. Using a terminal, clone the adoc-howto repository (this repository) onto your computer.

    git clone https://github.com/datastax/adoc-howto.git
  2. cd into the cloned repo.

    cd adoc-howto
  3. 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
  4. Create a working branch.

    git checkout -b <working-branch>

    Replace <working-branch> with a descriptive name or a related JIRA ticket number.

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

  6. Preview your changes by running a local build.

  7. Commit your changes.

    git commit -m "<description-of-changes>"
  8. 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.

  1. Create your pull request against the main branch.

  2. Assign someone from the docs team as a reviewer.

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 adoc-howto repo and checked out the main branch (see Working with Docs Contributor’s Guide docs for more information).

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

./build-locally.sh contributors-guide
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/adoc-howto/build/contributors-guide 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.

To view the generated HTML files directly
  1. Copy the entire file:/// path from the terminal output, and open it in a web browser.

  2. In the file browser, click docs, then click on any of the .html files.

  3. From here, you can browse the documentation just like you would on docs.datastax.com.

  4. 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
  1. 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!               │
       │                                                    │
       └────────────────────────────────────────────────────┘
  2. Copy the Local: address (in this case, http://localhost:3000) and open it in a web browser.

  3. From the Index of adoc-howto/ page, click build/ > contributors-guide/ > docs/

  4. From here, you can browse the documentation just like you would on docs.datastax.com.

  5. Once you’re done viewing the documentation, go back to your terminal window and press Ctrl+C to shut down the web server.

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

About

Asciidoc How-to guide for use with several DataStax documentation guides. We use AsciiDoc for writing documentation, and want users to know how to contribute.

Resources

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published