This repo contains the documentation source files for the DataStax Luna Streaming documentation.
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 Luna Streaming 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 Luna Streaming docs below.
Before following the steps below, first make sure that you have git installed on your computer.
-
Using a terminal, clone the pulsar-docs repository (this repository) onto your computer.
git clone https://github.com/datastax/pulsar-docs.git
-
cd
into the cloned repo.cd pulsar-docs
-
If you have previously cloned the repo, switch to the
main
branch and do agit 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 thedocs-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>
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 branch.
-
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.
You can generate the HTML docs locally to view changes and check your work.
Note that these steps assume you’ve already cloned the pulsar-docs repo and checked out the main
branch (see Working with Luna Streaming docs for more information).
Using a terminal, cd
into the cloned repo directory and run the following command:
./build-locally.sh luna-streaming
Important
|
Dependencies
The |
If the docs built successfully, you’ll see output similar to the following:
Site generation complete!
Open file:///Users/your-user-name/pulsar-docs/build/luna-streaming 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.
-
Y - Select to view the site build with the advanced functionality of a web server: To view the docs using the local web server.
-
N - Select to view only the generated docs HTML: To view the generated HTML files directly.
-
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.
-
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 pulsar-docs/ page, click build/ > luna-streaming/ > 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.
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
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.