Updates for unified build (#406)

* Updates for unified doc site

* Add workflow for pull request draft builds

* Add unified docs assets

* Remove external-link-icon attribute references

---------

Co-authored-by: Eric Schneider <[email protected]>

Author: mlr

.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/[email protected]
+        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

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

docs/README.adoc

@@ -1,92 +1,158 @@
-= {company} {product} Docs
+= {product} Docs
 // Variables:
 :product: RAGStack
-:company: DataStax
+:repo-name: ragstack-ai
+:github-org: datastax
 // Settings:
+:toc: macro
 :!example-caption:
 :experimental:
 :hide-uri-scheme:
-:toc: macro
 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::[]
-// URLs:
-:url-org: https://github.com/datastax
+// 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-asciidoc-docs: https://docs.asciidoctor.org/asciidoc/latest/
+:url-docs-preview: http://docs-preview.datastax.com
+// External URLs:
+:asciidoc-language: https://docs.asciidoctor.org/asciidoc/latest/
+
+This repository contains the source files for the {product} documentation.
+
+toc::[]
+
+== Get started
+
+The documentation is written in {asciidoc-language}[AsciiDoc]-formatted source files located in the `modules` directory.
+
+=== Make a simple update
+
+For simple updates like fixing typos or modifying existing prose, it's easiest to edit the source files directly on GitHub.
+
+NOTE: You'll need Write privileges on the repository to edit files directly on GitHub.
+
+. Find the file you want to edit in the `modules` directory.
+
+. Click the *Edit* icon in the upper-right corner of the file view.
+
+. Make your changes in the editor.
+
+. Click *Commit changes...*
 
+. Enter a description for your commit and click *Propose changes*.
 
-Documentation source for {company} {product}.
+. On the *Open a pull request* screen, enter a title and description for your change, assign reviewers, then click *Create pull request*.
 
-== Build docs locally
+. 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.
 
-. Clone this repository.
+=== 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,shell]
+[source,bash,subs="attributes"]
 ----
-git clone https://github.com/datastax/ragstack-ai.git
+git clone {url-project-repo}.git
 ----
 
+. 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.
+
 . 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,shell]
+[source,bash]
 ----
 brew install nvm
 ----
 
 .. Use nvm to install Node.js.
 +
-[source,shell]
+[source,bash]
 ----
 nvm install --lts
 ----
 +
-[source,shell]
+[source,bash]
 ----
 nvm use --lts
 ----
 +
-[source,shell]
+[source,bash]
 ----
 nvm alias default node
 ----
 
 . Install the project dependencies.
 +
-[source,shell]
+[source,bash,subs="attributes"]
 ----
-cd ragstack-ai/docs
+cd {repo-name}
 ----
 +
-[source,shell]
+[source,bash]
 ----
 npm install
 ----
 
 . Build the site.
 +
-[source,shell]
+[source,bash]
 ----
-npm run build:local:ragstack
+npm run build:local
 ----
 +
 If the build was successful, you'll see the following output in your terminal:
 +
-[source,console]
+[source,console,subs="attributes"]
 ----
 Site generation complete!
-Open file:///absolute-path-to-repo/ragstack-ai/docs/build/site/index.html in a browser to view your site.
+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/antora-ragstack.yml

@@ -0,0 +1,14 @@
+name: ragstack
+version: ~
+title: 'RAGStack'
+start_page: ROOT:index.adoc
+asciidoc:
+  attributes:
+    company: 'DataStax'
+    product: 'RAGStack'
+    db-cassandra: 'Astra DB Serverless (Non-Vector)'
+    db-vector: 'Astra DB Serverless'
+    db-serverless: 'Astra DB Serverless'
+    astra-ui: 'Astra Portal'
+nav:
+- modules/ROOT/nav.adoc

docs/antora.yml

@@ -0,0 +1,110 @@
+const logger = require("@antora/logger")("asciidoctor:svg-macro");
+
+/**
+ * @example Inline Embedded SVG
+ * svg:ROOT:ui/icons/vector.svg[]
+ */
+function inlineSvgMacro({ contentCatalog, file }) {
+  return function () {
+    this.process((parent, target, attrs) => {
+      svgContent = getSvgContent(target, file, contentCatalog);
+      if (!svgContent) return;
+      return this.createInlinePass(
+        parent,
+        svgContent.replace("<svg", `<svg ${htmlAttrs(attrs)}`)
+      );
+    });
+  };
+}
+
+/**
+ * @example Block Embedded SVG
+ * svg::home:diagrams/graphic.svg[alt="My Graphic"]
+ */
+function blockSvgMacro({ contentCatalog, file }) {
+  return function () {
+    this.process((parent, target, attrs) => {
+      svgContent = getSvgContent(target, file, contentCatalog);
+      if (!svgContent) return;
+      const svgHtmlAttrs = htmlAttrs({ ...attrs, role: undefined });
+      const containerHtmlAttrs = attrs.role
+        ? `class="imageblock ${attrs.role}"`
+        : 'class="imageblock"';
+      const html =
+        `<div ${containerHtmlAttrs}><div class="content">` +
+        svgContent.replace("<svg", `<svg ${svgHtmlAttrs}`) +
+        "</div></div>";
+      return this.createBlock(parent, "pass", html);
+    });
+  };
+}
+
+/**
+ * This macro relies on the material-icons font being loaded in UI bundle.
+ *
+ * @example Material Icon
+ * icon:material-icons:menu_open[]
+ *
+ * @example Embedded SVG
+ * icon:ROOT:ui/icons/vector.svg[]
+ */
+function inlineIconMacro({ contentCatalog, file }) {
+  return function () {
+    this.process((parent, target, attrs) => {
+      if (target.startsWith("material-icons")) {
+        iconTarget = target
+          .replace("material-icons:", "")
+          .trim()
+          .replace("-", "_");
+        return this.createInlinePass(
+          parent,
+          `<i ${htmlAttrs(attrs, "material-icons icon")}>${iconTarget}</i>`
+        );
+      } else {
+        svgContent = getSvgContent(target, file, contentCatalog);
+        if (!svgContent) return;
+        return this.createInlinePass(
+          parent,
+          svgContent.replace("<svg", `<svg ${htmlAttrs(attrs, "svg icon")}`)
+        );
+      }
+    });
+  };
+}
+
+function getSvgContent(target, file, contentCatalog) {
+  svgFile = contentCatalog.resolveResource(target, file.src, "image", [
+    "image",
+  ]);
+  if (!svgFile)
+    return logger.error({ target, file }, `target of svg not found: ${target}`);
+  svgContent = svgFile.contents.toString();
+  if (!svgContent.startsWith("<svg"))
+    return logger.error({ target, file }, "file contents must be a valid svg");
+  return svgContent;
+}
+
+function htmlAttrs({ width, height, role, alt, title }, klass = "svg") {
+  return [
+    width && `width="${width}"`,
+    height && `height="${height}"`,
+    role ? `class="${klass} ${role}"` : `class="${klass}"`,
+    alt && `aria-label="${alt}"`,
+    title && `aria-label="${title}"`,
+    (alt || title) && 'role="img"',
+  ]
+    .filter(Boolean)
+    .join(" ");
+}
+
+/**
+ * @param { import("@asciidoctor/core/types").Asciidoctor.Extensions.Registry } registry
+ * @param context
+ */
+function register(registry, context) {
+  registry.inlineMacro("svg", inlineSvgMacro(context));
+  registry.blockMacro("svg", blockSvgMacro(context));
+  registry.inlineMacro("icon", inlineIconMacro(context));
+}
+
+module.exports.register = register;