|
1 | | -= DataStax CDC for Apache Cassandra documentation |
| 1 | += {company} {product} Docs |
| 2 | +// Variables: |
| 3 | +:company: DataStax |
| 4 | +:product: CDC for Apache Cassandra |
| 5 | +:repo-name: cdc-apache-cassandra |
| 6 | +:github-org: datastax |
| 7 | +// Settings: |
| 8 | +:toc: macro |
| 9 | +:!example-caption: |
| 10 | +:experimental: |
| 11 | +:hide-uri-scheme: |
| 12 | +ifdef::env-github[] |
| 13 | +:icons: font |
| 14 | +:toclevels: 1 |
| 15 | +:toc-title: Contents |
| 16 | +:tip-caption: :bulb: |
| 17 | +:note-caption: :information_source: |
| 18 | +:important-caption: :heavy_exclamation_mark: |
| 19 | +:caution-caption: :fire: |
| 20 | +:warning-caption: :warning: |
| 21 | +:badges: |
| 22 | +endif::[] |
| 23 | +// Project URLs: |
| 24 | +:url-github-org: https://github.com/{github-org} |
| 25 | +:url-project-repo: {url-github-org}/{repo-name} |
| 26 | +:url-ui-repo: https://github.com/riptano/docs-ui |
| 27 | +:url-playbook-repo: https://github.com/riptano/datastax-docs-site |
| 28 | +:url-contribute: |
| 29 | +:url-datastax: https://datastax.com |
| 30 | +:url-datastax-docs: https://docs.datastax.com |
| 31 | +:url-docs-preview: http://docs-preview.datastax.com |
| 32 | +// External URLs: |
| 33 | +:asciidoc-language: https://docs.asciidoctor.org/asciidoc/latest/ |
2 | 34 |
|
3 | | -This repo contains the source files for the {csc_pulsar_first} documentation. |
| 35 | +This repository contains the source files for the {company} {product} documentation. |
4 | 36 |
|
5 | | -The docs are written in asciidoc and use Antora to generate the output. |
| 37 | +toc::[] |
6 | 38 |
|
7 | | -== Dependencies |
| 39 | +== Get started |
8 | 40 |
|
9 | | -Antora requires NodeJS. Install NodeJS, then update project dependencies: |
| 41 | +The documentation is written in {asciidoc-language}[AsciiDoc]-formatted source files located in the `modules` directory. |
10 | 42 |
|
11 | | -[source,bash] |
12 | | ----- |
13 | | -brew install node |
14 | | ----- |
| 43 | +=== Make a simple update |
15 | 44 |
|
16 | | -Install Antora: |
| 45 | +For simple updates like fixing typos or modifying existing prose, it's easiest to edit the source files directly on GitHub. |
17 | 46 |
|
18 | | -[source,bash] |
19 | | ----- |
20 | | - |
21 | | ----- |
| 47 | +NOTE: You'll need Write privileges on the repository to edit files directly on GitHub. |
22 | 48 |
|
23 | | -== Create the antora config file |
| 49 | +. Find the file you want to edit in the `modules` directory. |
24 | 50 |
|
25 | | -Generate the antory.yaml file using the project version: |
| 51 | +. Click the *Edit* icon in the upper-right corner of the file view. |
26 | 52 |
|
27 | | -[source,bash] |
| 53 | +. Make your changes in the editor. |
| 54 | + |
| 55 | +. Click *Commit changes...* |
| 56 | + |
| 57 | +. Enter a description for your commit and click *Propose changes*. |
| 58 | + |
| 59 | +. On the *Open a pull request* screen, enter a title and description for your change, assign reviewers, then click *Create pull request*. |
| 60 | + |
| 61 | +. Once the pull request is open, an automatic draft preview build is triggered. |
| 62 | +Once complete, the build system posts a comment on the pull request with a link to the draft site for you to preview your changes. |
| 63 | + |
| 64 | +=== Edit docs locally |
| 65 | + |
| 66 | +If you need to make substantial updates to the documentation, you'll want to clone the repository so you can work with the source files locally. |
| 67 | + |
| 68 | +. Clone this repository |
| 69 | ++ |
| 70 | +[source,bash,subs="attributes"] |
28 | 71 | ---- |
29 | | -./gradlew docs:antoraConfig |
| 72 | +git clone {url-project-repo}.git |
30 | 73 | ---- |
31 | 74 |
|
32 | | -== Generating and viewing the HTML output locally |
| 75 | +. https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-personal-access-token-classic[Create a _classic_ personal access token] for your GitHub account. |
| 76 | +When configuring the token, set the *Expiration* to at least 90 days and select everything under the *Repo* https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/scopes-for-oauth-apps#available-scopes[scope]. |
| 77 | ++ |
| 78 | +[IMPORTANT] |
| 79 | +==== |
| 80 | +Copy your personal access token to a temporary location -- you'll need it later. |
| 81 | +==== |
| 82 | + |
| 83 | +. https://docs.github.com/en/enterprise-cloud@latest/authentication/authenticating-with-saml-single-sign-on/authorizing-a-personal-access-token-for-use-with-saml-single-sign-on[Authorize your personal access token] so that it can access repositories in the Riptano and DataStax organizations in GitHub. |
| 84 | + |
| 85 | +. https://docs.antora.org/antora/latest/playbook/private-repository-auth/#populate-credentials-directly[Populate the credential store] with your personal access token. |
| 86 | +For most people this means doing the following: |
| 87 | ++ |
| 88 | +.. Create the file `$HOME/.git-credentials` and open it in your editor. |
| 89 | +.. Add the following line: |
| 90 | ++ |
| 91 | +[source,subs="verbatim,quotes"] |
| 92 | +---- |
| 93 | +https://**TOKEN**:@github.com |
| 94 | +---- |
| 95 | ++ |
| 96 | +Replace *`TOKEN`* with the personal access token you copied from GitHub. |
| 97 | +.. Save and close the file. |
33 | 98 |
|
34 | | -The docs can be generated locally during development, to check work. |
| 99 | +. If you don't already have Node.js installed, do the following: |
35 | 100 |
|
| 101 | +.. Install https://github.com/nvm-sh/nvm[nvm]. |
| 102 | ++ |
| 103 | +If you're on macOS, you can install nvm using https://brew.sh/[Homebrew]: |
| 104 | ++ |
36 | 105 | [source,bash] |
37 | 106 | ---- |
38 | | -npm run build:local |
| 107 | +brew install nvm |
39 | 108 | ---- |
40 | 109 |
|
41 | | -Output files are located in the build/site directory. |
42 | | - |
43 | | -== Publishing the HTML output |
| 110 | +.. Use nvm to install Node.js. |
| 111 | ++ |
| 112 | +[source,bash] |
| 113 | +---- |
| 114 | +nvm install --lts |
| 115 | +---- |
| 116 | ++ |
| 117 | +[source,bash] |
| 118 | +---- |
| 119 | +nvm use --lts |
| 120 | +---- |
| 121 | ++ |
| 122 | +[source,bash] |
| 123 | +---- |
| 124 | +nvm alias default node |
| 125 | +---- |
44 | 126 |
|
45 | | -To generate files for publishing: |
| 127 | +. Install the project dependencies. |
| 128 | ++ |
| 129 | +[source,bash,subs="attributes"] |
| 130 | +---- |
| 131 | +cd {repo-name}/docs |
| 132 | +---- |
| 133 | ++ |
| 134 | +[source,bash] |
| 135 | +---- |
| 136 | +npm install |
| 137 | +---- |
46 | 138 |
|
| 139 | +. Build the site. |
| 140 | ++ |
47 | 141 | [source,bash] |
48 | 142 | ---- |
49 | | -npm run build:publish |
| 143 | +npm run build:local |
50 | 144 | ---- |
| 145 | ++ |
| 146 | +If the build was successful, you'll see the following output in your terminal: |
| 147 | ++ |
| 148 | +[source,console,subs="attributes"] |
| 149 | +---- |
| 150 | +Site generation complete! |
| 151 | +Open file:///Users/USERNAME/repos/{repo-name}/build/site/index.html in a browser to view your site. |
| 152 | +---- |
| 153 | ++ |
| 154 | +To view the site, paste the entire `\file:///` path into your browser's address bar and press kbd:[Return]. |
| 155 | + |
| 156 | +[#publish-docs] |
| 157 | +== Publish docs |
| 158 | + |
| 159 | +To learn how to publish documentation to {url-datastax-docs}, see the {url-playbook-repo}#deploy-production[datastax-docs-site README]. |
0 commit comments