Skip to content

Commit 894a736

Browse files
mendonkmendonk
committed
readme
1 parent 562391d commit 894a736

File tree

1 file changed

+182
-16
lines changed

1 file changed

+182
-16
lines changed

‎README.adoc

Lines changed: 182 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -1,35 +1,201 @@
1-
= DataStax Pulsar Connector documentation
1+
= DataStax {product} Documentation
2+
:toc: macro
3+
:product: Pulsar Connector
4+
:product-repo-name: pulsar-sink-docs
5+
:product-repo-name-long: datastax/pulsar-sink-docs
6+
:product-repo-link: https://github.com/datastax/pulsar-sink-docs.git
7+
:product-branch-name: main
8+
:docset-name: pulsarConnector
9+
:product-branch-link: https://github.com/riptano/luna-docs/tree/main
10+
:install-git-link: https://github.com/git-guides/install-git
11+
:create-pr-link: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request
12+
:nvm-link: https://github.com/nvm-sh/nvm
13+
:homebrew-link: https://brew.sh/
14+
:asciidoctor-link: https://docs.asciidoctor.org/asciidoc/latest/
15+
:antora-link: https://docs.antora.org/antora/latest/
16+
:contributor-docs-link: https://docs.google.com/presentation/d/10RjxURHpJ8gwac0dCZ02pKo31nGhem29Z8-xERApyWU/edit?usp=sharing
17+
:web-server-link: https://www.npmjs.com/package/serve
218

3-
This repo contains the source files for the Pulsar Connector documentation.
19+
This repo contains the documentation source files for the DataStax {product} documentation.
420

5-
The docs are written in asciidoc and use Antora to generate the output.
21+
The docs are written in {asciidoctor-link}[AsciiDoc] and use {antora-link}[Antora] to generate the HTML output.
622

7-
== Dependencies
23+
toc::[]
824

9-
Antora requires NodeJS. Install NodeJS, then update project dependencies:
25+
== Contributing to the docs
1026

11-
[source,bash]
27+
Although this repo is maintained by the DataStax Docs team, contributions from the community are gratefully accepted, and encouraged.
28+
29+
_Why should you contribute to the {product} docs?_::
30+
* It makes the Docs team's job easier.
31+
* It makes your job easier.
32+
* It helps DataStax and Cassandra users more quickly.
33+
34+
_How do you contribute?_::
35+
The majority of DataStax documentation source files are written in AsciiDoc, a lightweight, human-readable markup language.
36+
You can contribute to the documentation by adding content to, or editing, the AsciiDoc files in this repo.
37+
38+
For instructions, see <<writing-asciidoc>> below.
39+
40+
[[writing-asciidoc]]
41+
== Working with {product} docs
42+
43+
Before following the steps below, first make sure that you have {install-git-link}[git] installed on your computer.
44+
45+
. Using a terminal, clone the {product-repo-link}[{product-repo-name}] repository (this repository) onto your computer.
46+
+
47+
[source,shell,subs="attributes+"]
1248
----
13-
brew install node
14-
npm install
49+
git clone {product-repo-link}
50+
----
51+
. `cd` into the cloned repo.
52+
+
53+
[source,shell,subs="attributes+"]
54+
----
55+
cd {product-repo-name}
56+
----
57+
. If you have previously cloned the repo, switch to the `{product-branch-name}` branch and do a `git pull` to get the latest changes.
58+
+
59+
[source,shell,subs="attributes+"]
60+
----
61+
git checkout {product-branch-name} && git pull
1562
----
63+
. Create a working branch.
64+
+
65+
[source,shell,subs="attributes+"]
66+
----
67+
git checkout -b <working-branch>
68+
----
69+
+
70+
Replace `<working-branch>` with a descriptive name or a related JIRA ticket number.
71+
. 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).
72+
Make sure to save your changes once you're done making edits.
73+
+
74+
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.
75+
. Preview your changes by running a <<build-locally,local build>>.
76+
. Commit your changes.
77+
+
78+
[source,shell,subs="attributes+"]
79+
----
80+
git commit -m "<description-of-changes>"
81+
----
82+
. Push your changes to GitHub.
83+
+
84+
[source,shell,subs="attributes+"]
85+
----
86+
git push -u origin <working-branch>
87+
----
88+
89+
=== Submitting your changes
90+
91+
Once all of your changes are pushed to GitHub, you'll need to submit them for review by creating a {create-pr-link}[pull request].
92+
93+
. Create your pull request against the {product-branch-link}[{product-branch-name}] branch.
94+
. Assign someone from the docs team as a reviewer.
95+
* https://github.com/jgillenwater[@jgillenwater]
96+
* https://github.com/polandll[@polandll]
97+
98+
The docs team will review, ask questions, make requests, and merge your changes.
99+
The docs team will then update the published documentation to reflect your changes.
100+
101+
For more information on contributing to the docs, click {contributor-docs-link}[here].
16102

103+
[[build-locally]]
17104
== Generating and viewing the HTML output locally
18105

19-
The docs can be generated locally during development, to check work.
106+
You can generate the HTML docs locally to view changes and check your work.
107+
Note that these steps assume you've already cloned the {product-repo-link}[{product-repo-name}] repo and checked out the `{product-branch-name}` branch (see <<writing-asciidoc>> for more information).
20108

21-
[source,bash]
109+
Using a terminal, `cd` into the cloned repo directory and run the following command:
110+
111+
[source,shell,subs="attributes+"]
112+
----
113+
./build-locally.sh {docset-name}
114+
----
115+
116+
.Dependencies
117+
[IMPORTANT]
118+
====
119+
The `build-locally.sh` script requires {nvm-link}[`nvm`] to be installed on your system in order to install and update the rest of the required dependencies.
120+
If you're running macOS and have {homebrew-link}[Homebrew] installed, the script will automatically install `nvm` for you.
121+
If you're running on another platform (or don't use Homebrew), you'll need to manually install `nvm` before running the above command.
122+
====
123+
124+
If the docs built successfully, you'll see output similar to the following:
125+
126+
[source,console,subs="attributes+"]
127+
----
128+
Site generation complete!
129+
Open file:///Users/your-user-name/{product-repo-name}/build/{docset-name} in a browser to view your site.
130+
131+
Do you want to start a local web server for viewing the generated docs? (Y or N)
132+
----
133+
134+
The `build-locally.sh` script prints the local file path of the generated docs, and prompts you about starting a local {web-server-link}[web server] for viewing the docs.
135+
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.
136+
(The web server is only required for viewing certain advanced functionality of the site build.)
137+
138+
.To view the generated HTML files directly (most users)
139+
. Copy the entire `file:` path from the terminal output, and open it in a web browser.
140+
. In the file browser, click *docs*, then click on any of the `.html` files.
141+
. From here, you can browse the documentation just like you would on docs.datastax.com.
142+
. If you end up making further edits to the documentation, simply run the `build-locally.sh` script again to view your latest changes.
143+
144+
.To view the docs using the local web server (advanced users)
145+
. When prompted to start the local web server, type *Y* and press *Return*.
146+
+
147+
When the web server starts up, you'll see output similar to the following:
148+
+
22149
----
23-
npm run build:local
150+
┌────────────────────────────────────────────────────┐
151+
│ │
152+
│ Serving! │
153+
│ │
154+
│ - Local: http://localhost:3000 │
155+
│ - On Your Network: http://192.168.86.141:3000 │
156+
│ │
157+
│ Copied local address to clipboard! │
158+
│ │
159+
└────────────────────────────────────────────────────┘
24160
----
161+
. Copy the `Local:` address (in this case, `\http://localhost:3000`) and open it in a web browser.
162+
. From the *Index of {product-repo-name}/* page, click *build/ > {docset-name}/ > docs/*
163+
. From here, you can browse the documentation just like you would on docs.datastax.com.
164+
. Once you're done viewing the documentation, go back to your terminal window and press *Ctrl+C* to shut down the web server.
165+
. If you end up making further edits to the documentation, simply run the `build-locally.sh` script again to view your latest changes.
25166

26-
Output files are located in the build directory.
167+
== Repo dependencies
27168

28-
== Publishing the HTML output
169+
The `build-locally.sh` script should take care of installations required to build the docs.
170+
However, if you get a message that you need to install NodeJS, run the following commands (macOS):
29171

30-
To generate files for publishing:
172+
[source,shell,subs="attributes+"]
173+
----
174+
brew install node
175+
----
31176

32-
[source,bash]
177+
[source,shell,subs="attributes+"]
33178
----
34-
npm run build:publish
179+
npm install
35180
----
181+
182+
=== Dependencies in package.json
183+
184+
There are some key dependencies for building the DataStax documentation.
185+
186+
[source,json,subs="attributes+"]
187+
----
188+
"dependencies": {
189+
"@antora/cli": "~3.0.1",
190+
"@antora/site-generator-default": "~3.0.1",
191+
"linkinator": "~3.0.3",
192+
"async": "~3.2.4",
193+
"mobx": "~6.0.4",
194+
"react": "~16.8.4",
195+
"react-dom": "~16.8.4",
196+
"rxjs": "~7.0.1",
197+
"styled-components": "~5.1.1"
198+
}
199+
----
200+
201+
`@antora/cli` and `@antora/site-generator-default` are requirements to build with Antora.

0 commit comments

Comments
 (0)