Redesign documentation versioning: one sitewide Stable/Development toggle

.github/workflows/cut-versions.yml

@@ -0,0 +1,97 @@
+name: Auto-cut Stable versions
+
+# Checks every versioned tool for a newer tag upstream (see
+# scripts/auto-cut-versions.js) and, if one exists, cuts Stable and
+# re-cuts Previous versions via scripts/cut-version.js, then merges the
+# result straight to main — see "Cutting Stable or Previous versions" in
+# docs/contribute/versioning.mdx. Fully automatic end to end: a newer tag
+# existing upstream is itself the only signal this waits for, and the
+# build + test run below is the gate, not a human. Runs on a schedule so
+# nobody has to remember to run that script by hand after a release, and
+# nobody has to click merge either.
+
+on:
+  schedule:
+    - cron: '0 6 * * *' # daily, 06:00 UTC
+  workflow_dispatch:
+
+permissions:
+  contents: write
+  pull-requests: write
+
+concurrency:
+  group: auto-cut-versions
+  cancel-in-progress: false
+
+jobs:
+  auto-cut:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      # See the matching comment in ci.yml for why both are needed.
+      - name: Install Doxygen and Graphviz
+        run: sudo apt-get update && sudo apt-get install -y doxygen graphviz
+
+      - name: Check for new tags and cut Stable
+        run: node scripts/auto-cut-versions.js
+
+      - name: Determine whether anything was cut
+        id: check
+        run: |
+          if [ -f cut-version-summary.md ]; then
+            echo "changed=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "changed=false" >> "$GITHUB_OUTPUT"
+          fi
+
+      # A cut is never pushed unverified — build/test have to pass on the
+      # actual result before a PR is opened or updated with it.
+      - name: Build
+        if: steps.check.outputs.changed == 'true'
+        run: npm run build
+
+      - name: Test
+        if: steps.check.outputs.changed == 'true'
+        run: npm test
+
+      # One fixed branch, force-pushed each run — a run the next day with
+      # no further upstream changes has nothing new to add, and a run
+      # while an earlier auto-cut PR somehow still exists updates that
+      # same PR in place instead of opening a duplicate (normally there
+      # is none: the merge below closes it out the same run it's opened).
+      # Still goes through a PR (not a direct push to main) so the cut
+      # has a normal commit/PR record — merging it is what's automatic
+      # here, not the record-keeping.
+      - name: Open, then merge, the PR
+        if: steps.check.outputs.changed == 'true'
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          BRANCH="automated/cut-versions"
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git checkout -B "$BRANCH"
+          git add -A -- '*_versioned_docs' '*_versioned_sidebars' '*_versions.json' versioned-tools-stable.json
+          git commit -m "$(printf 'Auto-cut Stable version(s)\n\n%s' "$(cat cut-version-summary.md)")"
+          git push --force origin "$BRANCH"
+          if [ -z "$(gh pr list --head "$BRANCH" --state open --json number --jq '.[0].number')" ]; then
+            gh pr create --title "Auto-cut Stable version(s)" --body-file cut-version-summary.md --head "$BRANCH" --base main
+          else
+            gh pr edit "$BRANCH" --body-file cut-version-summary.md
+          fi
+          # Build + Test above already validated this exact commit, so
+          # merge immediately rather than waiting on anything further —
+          # if branch protection on main blocks this (e.g. it requires
+          # its own separate status checks or reviews), this fails loudly
+          # here and the PR is left open for a human, rather than merging
+          # partway or silently doing nothing.
+          gh pr merge "$BRANCH" --merge --delete-branch

.gitignore

@@ -48,6 +48,10 @@ versioned-tools/**/*.md
 /doxygen2docusaurus.json
 /scripts/generated/
 
+# scripts/auto-cut-versions.js's own scratch output — read by
+# .github/workflows/cut-versions.yml, never committed itself.
+/cut-version-summary.md
+
 # Editor / machine-specific
 .vscode/
 

adaptive-grippers-cpp_versioned_docs/version-stable/docs/index.mdx

@@ -0,0 +1,15 @@
+---
+title: Introduction guides
+sidebar_label: Introduction guides
+---
+
+import Readme from '../_readme.md';
+
+<Readme />
+
+## Contents
+
+{/* AUTO-GENERATED-GUIDES-TABLE:START */}
+
+{/* AUTO-GENERATED-GUIDES-TABLE:END */}
+

adaptive-grippers-cpp_versioned_docs/version-stable/index.mdx

@@ -15,6 +15,14 @@ import Readme from './_readme.md';
 
 <Readme />
 
+## Get started
+
+{/* AUTO-GENERATED-SUBPAGES-TABLE:START */}
+<div className="subpage-links">
+  <a className="subpage-link" href="docs">Introduction guides</a>
+</div>
+{/* AUTO-GENERATED-SUBPAGES-TABLE:END */}
+
 ## Source Code
 
 <a className="cta-button" href="https://github.com/robotiq/grippers/tree/v1.0.0"><img src="/img/GitHub_Invertocat_blue.png" alt="" style={{height: '1.9em', width: 'auto', verticalAlign: 'middle'}} /> GitHub Repository</a>

adaptive-grippers-cpp_versioned_sidebars/version-previous-versions-sidebars.json

@@ -14,9 +14,13 @@
           "label": "Libraries",
           "items": [
             {
-              "type": "doc",
-              "id": "index",
-              "label": "C++"
+              "type": "category",
+              "label": "C++",
+              "link": {
+                "type": "doc",
+                "id": "index"
+              },
+              "items": []
             },
             {
               "type": "link",

adaptive-grippers-cpp_versioned_sidebars/version-stable-sidebars.json

@@ -14,9 +14,23 @@
           "label": "Libraries",
           "items": [
             {
-              "type": "doc",
-              "id": "index",
-              "label": "C++"
+              "type": "category",
+              "label": "C++",
+              "link": {
+                "type": "doc",
+                "id": "index"
+              },
+              "items": [
+                {
+                  "type": "category",
+                  "label": "Introduction guides",
+                  "link": {
+                    "type": "doc",
+                    "id": "docs/index"
+                  },
+                  "items": []
+                }
+              ]
             },
             {
               "type": "link",

adaptive-grippers-cpp_versions.json

@@ -1,4 +1,4 @@
 [
-  "stable",
-  "previous-versions"
+  "previous-versions",
+  "stable"
 ]