Updates for unified build (#176)

---------

Co-authored-by: Eric Schneider <37347760+eric-schneider@users.noreply.github.com>

.github/workflows/dispatch-deploy-draft.yml

@@ -0,0 +1,45 @@
+name: Deploy Draft
+
+on:
+  pull_request:
+    branches:
+      - '*'
+
+jobs:
+  dispatch-deploy:
+    runs-on: ubuntu-latest
+
+    steps:
+        # Determine the build branch and draft branch for dispatch.
+      - name: Determine Dispatch Parameters
+        run: |
+          if [ "${{ github.event_name }}" == "pull_request" ]; then
+            # If this workflow is kicked off by a pull request, build
+            # a draft using the pull request base branch and PR branch.
+            build_branch="${{ github.base_ref }}"
+            draft_branch="${{ github.event.pull_request.head.ref }}"
+          else
+            if [ "$(basename ${{ github.event.ref }})" == "stage" ]; then
+              # This was a merge to stage so kick off a build to update stage draft.
+              build_branch=stage
+              draft_branch=stage
+            else
+              # Otherwise this is a push to one of the source branches so
+              # dispatch a build for the main draft to pick up the changes.
+              build_branch=main
+              draft_branch=main
+            fi
+          fi
+          echo "build_branch=$build_branch" >> $GITHUB_OUTPUT
+          echo "draft_branch=$draft_branch" >> $GITHUB_OUTPUT
+        id: branches
+
+      - name: Deploy Draft
+        uses: convictional/trigger-workflow-and-wait@v1.6.1
+        with:
+          owner: riptano
+          repo: datastax-docs-site
+          github_token: ${{ secrets.DISPATCH_GITHUB_TOKEN }}
+          github_user: ${{ secrets.DISPATCH_GITHUB_USER }}
+          workflow_file_name: deploy-draft.yml
+          client_payload: '{ "build_repository": "${{ github.event.repository.full_name }}", "build_branch": "${{ steps.branches.outputs.build_branch }}", "draft_branch": "${{ steps.branches.outputs.draft_branch }}", "pull_request_number": "${{ github.event.pull_request.number }}" }'

docs/.gitignore

@@ -0,0 +1,15 @@
+#OS
+**/.DS_Store
+**/.git-credentials
+
+#IDE
+**/.vscode/
+**/.idea
+**/*.iml
+*.http
+**/.java-version
+
+#build
+**/package-lock.json
+**/node_modules/
+/build/

docs/README.adoc

@@ -1,50 +1,159 @@
-= DataStax CDC for Apache Cassandra documentation
+= {company} {product} Docs
+// Variables:
+:company: DataStax
+:product: CDC for Apache Cassandra
+:repo-name: cdc-apache-cassandra
+:github-org: datastax
+// Settings:
+:toc: macro
+:!example-caption:
+:experimental:
+:hide-uri-scheme:
+ifdef::env-github[]
+:icons: font
+:toclevels: 1
+:toc-title: Contents
+:tip-caption: :bulb:
+:note-caption: :information_source:
+:important-caption: :heavy_exclamation_mark:
+:caution-caption: :fire:
+:warning-caption: :warning:
+:badges:
+endif::[]
+// Project URLs:
+:url-github-org: https://github.com/{github-org}
+:url-project-repo: {url-github-org}/{repo-name}
+:url-ui-repo: https://github.com/riptano/docs-ui
+:url-playbook-repo: https://github.com/riptano/datastax-docs-site
+:url-contribute:
+:url-datastax: https://datastax.com
+:url-datastax-docs: https://docs.datastax.com
+:url-docs-preview: http://docs-preview.datastax.com
+// External URLs:
+:asciidoc-language: https://docs.asciidoctor.org/asciidoc/latest/
 
-This repo contains the source files for the {csc_pulsar_first} documentation.
+This repository contains the source files for the {company} {product} documentation.
 
-The docs are written in asciidoc and use Antora to generate the output.
+toc::[]
 
-== Dependencies
+== Get started
 
-Antora requires NodeJS. Install NodeJS, then update project dependencies:
+The documentation is written in {asciidoc-language}[AsciiDoc]-formatted source files located in the `modules` directory.
 
-[source,bash]
-----
-brew install node
-----
+=== Make a simple update
 
-Install Antora:
+For simple updates like fixing typos or modifying existing prose, it's easiest to edit the source files directly on GitHub.
 
-[source,bash]
-----
-npm i -g @antora/cli@2.3 @antora/site-generator-default@2.3
-----
+NOTE: You'll need Write privileges on the repository to edit files directly on GitHub.
 
-== Create the antora config file
+. Find the file you want to edit in the `modules` directory.
 
-Generate the antory.yaml file using the project version:
+. Click the *Edit* icon in the upper-right corner of the file view.
 
-[source,bash]
+. Make your changes in the editor.
+
+. Click *Commit changes...*
+
+. Enter a description for your commit and click *Propose changes*.
+
+. On the *Open a pull request* screen, enter a title and description for your change, assign reviewers, then click *Create pull request*.
+
+. Once the pull request is open, an automatic draft preview build is triggered.
+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.
+
+=== Edit docs locally
+
+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.
+
+. Clone this repository
++
+[source,bash,subs="attributes"]
 ----
-./gradlew docs:antoraConfig
+git clone {url-project-repo}.git
 ----
 
-== Generating and viewing the HTML output locally
+. 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.
+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].
++
+[IMPORTANT]
+====
+Copy your personal access token to a temporary location -- you'll need it later.
+====
+
+. 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.
+
+. https://docs.antora.org/antora/latest/playbook/private-repository-auth/#populate-credentials-directly[Populate the credential store] with your personal access token.
+For most people this means doing the following:
++
+..  Create the file `$HOME/.git-credentials` and open it in your editor.
+.. Add the following line:
++
+[source,subs="verbatim,quotes"]
+----
+https://**TOKEN**:@github.com
+----
++
+Replace *`TOKEN`* with the personal access token you copied from GitHub.
+.. Save and close the file.
 
-The docs can be generated locally during development, to check work.
+. If you don't already have Node.js installed, do the following:
 
+.. Install https://github.com/nvm-sh/nvm[nvm].
++
+If you're on macOS, you can install nvm using https://brew.sh/[Homebrew]:
++
 [source,bash]
 ----
-npm run build:local
+brew install nvm
 ----
 
-Output files are located in the build/site directory.
-
-== Publishing the HTML output
+.. Use nvm to install Node.js.
++
+[source,bash]
+----
+nvm install --lts
+----
++
+[source,bash]
+----
+nvm use --lts
+----
++
+[source,bash]
+----
+nvm alias default node
+----
 
-To generate files for publishing:
+. Install the project dependencies.
++
+[source,bash,subs="attributes"]
+----
+cd {repo-name}/docs
+----
++
+[source,bash]
+----
+npm install
+----
 
+. Build the site.
++
 [source,bash]
 ----
-npm run build:publish
+npm run build:local
 ----
++
+If the build was successful, you'll see the following output in your terminal:
++
+[source,console,subs="attributes"]
+----
+Site generation complete!
+Open file:///Users/USERNAME/repos/{repo-name}/build/site/index.html in a browser to view your site.
+----
++
+To view the site, paste the entire `\file:///` path into your browser's address bar and press kbd:[Return].
+
+[#publish-docs]
+== Publish docs
+
+To learn how to publish documentation to {url-datastax-docs}, see the {url-playbook-repo}#deploy-production[datastax-docs-site README].

docs/docs-src/core/antora.yml

@@ -0,0 +1,17 @@
+name: cdc-for-cassandra
+title: DataStax CDC for Apache Cassandra
+version: '2.2.9'
+display_version: '2.2.9'
+start_page: index.adoc
+asciidoc:
+  attributes:
+    cdc_cass_first: 'DataStax CDC for Apache Cassandra(R)'
+    cdc_cass: 'CDC for Cassandra'
+    csc_pulsar_first: 'DataStax Cassandra Source Connector for Apache Pulsar(TM)'
+    csc_pulsar: 'CSC for Pulsar'
+    cdc_pulsar: 'CDC for Cassandra'
+    luna_version: '2.10'
+    pulsar_version: '2.10'
+    version: '2.2.9' # cdc-apache-cassandra latest {version}
+nav:
+- modules/ROOT/nav.adoc

docs/docs-src/core/modules/ROOT/nav.adoc

@@ -4,4 +4,5 @@
 * xref:backfill-cli.adoc[]
 * xref:faqs.adoc[]
 * xref:cdc-cassandra-events.adoc[]
+* xref:stringMappings.adoc[]
 * xref:cdcExample.adoc[]

docs/docs-src/core/modules/ROOT/pages/index.adoc

@@ -1,7 +1,7 @@
 = About {cdc_cass}
 
 {cdc_cass_first} is open-source software (OSS) that sends Cassandra mutations
-for tables having Change Data Capture (CDC) enabled to https://www.datastax.com/products/luna-streaming[Luna Streaming] or https://pulsar.apache.org/[Apache Pulsar™], which in turn can write the data to platforms such as Elasticsearch® or Snowflake®.
+for tables having Change Data Capture (CDC) enabled to https://www.datastax.com/products/luna-streaming[Luna Streaming] or https://pulsar.apache.org/[Apache Pulsar(TM)], which in turn can write the data to platforms such as Elasticsearch(R) or Snowflake(R).
 
 == Key Features
 
@@ -85,12 +85,12 @@ For each update to the table, an MD5 digest is calculated to de-duplicate the up
 [#supported-databases]
 == Supported databases
 
-* Apache Cassandra® 3.11.x and 4.x databases
+* Apache Cassandra(R) 3.11.x and 4.x databases
 * Datastax Server Enterprise 6.8.16+
 
 == Supported Cassandra data structures
 
-The following CQL data types are encoded as AVRO logical types: 
+The following CQL data types are encoded as AVRO logical types:
 
 * ascii (string)
 * bigint (long)
@@ -134,7 +134,7 @@ If a row update contains both supported and unsupported data types, the event wi
 
 {cdc_cass} has the following limitations:
 
-* Does not manage table truncates. The `TRUNCATE [TABLE]` command should not be used. 
+* Does not manage table truncates. The `TRUNCATE [TABLE]` command should not be used.
 * Does not sync data available before starting the CDC agent.
 * Does not replay logged batches.
 * Does not manage time-to-live.