Decouple docs from DataStax docs site (#661)

Author: eric-schneider

docs/.nvmrc

@@ -0,0 +1 @@
+lts/*

docs/README.adoc

@@ -1,158 +1,34 @@
-= {product} Docs
+= {product} documentation
 // Variables:
 :product: RAGStack
-:repo-name: ragstack-ai
-:github-org: datastax
 // Settings:
 :toc: macro
+:idprefix:
+:idseparator: -
 :!example-caption:
 :experimental:
 :hide-uri-scheme:
+ifndef::env-github[:icons: font]
 ifdef::env-github[]
-:icons: font
-:toclevels: 1
-:toc-title: Contents
+:toclevels: 2
 :tip-caption: :bulb:
-:note-caption: :information_source:
+:note-caption: :paperclip:
 :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/
+:url-asciidoc-lang: https://docs.asciidoctor.org/asciidoc/latest/
+:url-antora-docs: https://docs.antora.org/antora/latest/
 
-This repository contains the source files for the {product} documentation.
 
-toc::[]
+The {product} documentation is written in https://docs.asciidoctor.org/asciidoc/latest/[AsciiDoc].
+The source files in the `link:modules/[]` folder are organized into a documentation component as identified by the `link:antora.yml[]` file.
 
-== Get started
+== Build the docs
 
-The documentation is written in {asciidoc-language}[AsciiDoc]-formatted source files located in the `modules` directory.
+You can use https://antora.org/[Antora] to build a static HTML version of the documentation.
 
-=== 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*.
-
-. 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"]
-----
-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,bash]
-----
-brew install nvm
-----
-
-.. Use nvm to install Node.js.
-+
-[source,bash]
-----
-nvm install --lts
-----
-+
-[source,bash]
-----
-nvm use --lts
-----
-+
-[source,bash]
-----
-nvm alias default node
-----
-
-. Install the project dependencies.
-+
-[source,bash,subs="attributes"]
-----
-cd {repo-name}
-----
-+
-[source,bash]
-----
-npm install
-----
-
-. Build the site.
-+
-[source,bash]
-----
-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].
+To build and preview the documentation locally, follow the instructions in the file link:local-antora-playbook.yml[] at the root of this repository.
+To learn more about how to build a documentation site with Antora, see the https://docs.antora.org/antora/latest/install-and-run-quickstart/[Install and Run Antora Quickstart].

docs/antora-extensions/unlisted-pages-extension.js

@@ -0,0 +1,40 @@
+module.exports.register = function ({ config }) {
+  const { addToNavigation, unlistedPagesHeading = 'Unlisted Pages' } = config
+  const logger = this.getLogger('unlisted-pages-extension')
+  this
+    .on('navigationBuilt', ({ contentCatalog }) => {
+      contentCatalog.getComponents().forEach(({ versions }) => {
+        versions.forEach(({ name: component, version, navigation: nav, url: defaultUrl }) => {
+          const navEntriesByUrl = getNavEntriesByUrl(nav)
+          const unlistedPages = contentCatalog
+            .findBy({ component, version, family: 'page' })
+            .filter((page) => page.out)
+            .reduce((collector, page) => {
+              if ((page.pub.url in navEntriesByUrl) || page.pub.url === defaultUrl) return collector
+              logger.warn({ file: page.src, source: page.src.origin }, 'detected unlisted page')
+              return collector.concat(page)
+            }, [])
+          if (unlistedPages.length && addToNavigation) {
+            nav.push({
+              content: unlistedPagesHeading,
+              items: unlistedPages.map((page) => {
+                const title = 'navtitle' in page.asciidoc
+                  ? page.asciidoc.navtitle
+                  : (page.src.module === 'ROOT' ? '' : page.src.module + ':') + page.src.relative
+                return { content: title, url: page.pub.url, urlType: 'internal' }
+              }),
+              root: true,
+            })
+          }
+        })
+      })
+    })
+}
+
+function getNavEntriesByUrl (items = [], accum = {}) {
+  items.forEach((item) => {
+    if (item.urlType === 'internal') accum[item.url.split('#')[0]] = item
+    getNavEntriesByUrl(item.items, accum)
+  })
+  return accum
+}

docs/antora.yml

@@ -4,12 +4,10 @@ title: 'RAGStack'
 start_page: ROOT:index.adoc
 asciidoc:
   attributes:
-    company: 'DataStax'
+    datastax: 'DataStax'
     product: 'RAGStack'
-    db-cassandra: 'Astra DB Serverless (Non-Vector)'
-    db-vector: 'Astra DB Serverless'
     db-serverless: 'Astra DB Serverless'
+    astra-db: 'Astra DB'
     astra-ui: 'Astra Portal'
-    graph-store: 'Graph Store'
 nav:
 - modules/ROOT/nav.adoc