[Docs] Rebuild JSDoc site as a pure function of manifest + git tags (#1553)

Replace the gh-pages branch cache with a stateless build so the published documentation site is fully reproducible from a curated manifest and the Git release tags. Every deploy rebuilds the complete site from scratch, so there is no branch state that can drift.

- Add tools/jsdoc/published-versions.json: a curated manifest (30 versions) that is the single source of truth for which versions are published.
- Rewrite tools/jsdoc/regenerate-published-docs.js as one linear build path: every manifest version is rebuilt from its Git release tag via `git worktree` + jsdoc (using the current template, so all versions render consistently), shared assets are hoisted to docs/_static, and the landing index is regenerated. Drop the gh-pages cache, prune/self-heal logic, the per-version asset copies, and all the old mode flags. Remaining flags: --out, --manifest (both now validate that a value follows the flag).
- package.json: replace `docs:gh-pages` / `docs:gh-pages:full` with a single `docs:publish` script.
- .github/workflows/deploy-docs.yml: set `contents: read`, remove the gh-pages fetch and write-back steps, run `npm run docs:publish`, and upload build/published-docs as the Pages artifact.
- tools/jsdoc/README.md: document the stateless manifest + tags model and the new naming; drop the obsolete "Recovering a Dropped Version" section and redundant gh-pages references.

Fix: #1552

Author: minggangw

.github/workflows/deploy-docs.yml

@@ -31,9 +31,6 @@ jobs:
           fetch-depth: 0
           fetch-tags: true
 
-      - name: Fetch gh-pages branch
-        run: git fetch origin gh-pages:refs/remotes/origin/gh-pages
-
       - name: Setup Node.js
         uses: actions/setup-node@v6
         with:
@@ -43,12 +40,12 @@ jobs:
         run: npm install --ignore-scripts --no-audit --no-fund
 
       - name: Build docs
-        run: npm run docs:gh-pages
+        run: npm run docs:publish
 
       - name: Upload Pages artifact
         uses: actions/upload-pages-artifact@v5
         with:
-          path: build/gh-pages-docs
+          path: build/published-docs
 
   deploy:
     needs: build

package.json

@@ -62,8 +62,7 @@
     "install": "node scripts/install.cjs",
     "postinstall": "npm run generate-messages",
     "docs": "make -C tools/jsdoc",
-    "docs:gh-pages": "node tools/jsdoc/regenerate-published-docs.js --branch origin/gh-pages --preserve-published",
-    "docs:gh-pages:full": "node tools/jsdoc/regenerate-published-docs.js --branch origin/gh-pages --full-rebuild",
+    "docs:publish": "node tools/jsdoc/regenerate-published-docs.js",
     "test": "node --expose-gc ./scripts/run_test.cjs && tsd && npm install --no-save electron && node test/electron/run_test.cjs",
     "test:coverage": "c8 node --expose-gc ./scripts/run_test.cjs && tsd && npm install --no-save electron && node test/electron/run_test.cjs",
     "test-idl": "node --expose-gc ./scripts/run_test.cjs --idl",

tools/jsdoc/README.md

@@ -1,8 +1,15 @@
 # JSDoc Workflow
 
 This directory contains the custom JSDoc template, the landing-page generator,
-and the staging script used to prepare the docs content that is published to the
-`gh-pages` branch.
+and the staging script used to prepare the docs content that is published to
+GitHub Pages.
+
+The published version set is curated in
+[`published-versions.json`](./published-versions.json). That manifest is the
+source of truth for which versions appear on the live docs site. Each staging
+run rebuilds the whole site from scratch: every listed version is rebuilt from
+its Git tag. The staged tree is therefore a pure function of the manifest plus
+the tags — there is no `gh-pages` branch state to maintain or drift out of sync.
 
 ## Commands
 
@@ -18,52 +25,46 @@ Output:
 Use this to verify the docs for the version currently declared in
 `package.json`.
 
-### `npm run docs:gh-pages`
+### `npm run docs:publish`
 
-Stage the publishable docs tree under `build/gh-pages-docs/`.
+Stage the full publishable docs tree under `build/published-docs/`.
 
 Behavior:
 
-- reads the currently published version set from `origin/gh-pages`
-- preserves that published history
-- regenerates docs for the current workspace version
+- reads the published version set from `published-versions.json`
+- rebuilds every listed version from its Git tag
 - rebuilds the staged landing page index
 
-This is the normal command to use for a new release.
-
-If you delete `build/` and rerun `npm run docs:gh-pages`, the staged tree will
-still contain all currently published versions. That command recreates
-`build/gh-pages-docs/` by copying the published docs snapshot from
-`origin/gh-pages`, then regenerating only the current workspace version.
+This is the normal command to use for a new release, and it is fully
+deterministic: deleting `build/` and rerunning reproduces the identical tree.
 
-### `npm run docs:gh-pages:full`
+This does **not** rebuild docs for every historical `rclnodejs` tag — only the
+curated subset listed in the manifest. To change which versions are published,
+edit `published-versions.json`.
 
-Fully rebuild the currently published docs history under
-`build/gh-pages-docs/`.
+The script reads the manifest next to it by default. Override the inputs only
+for testing:
 
-Behavior:
-
-- reads the published version set from `origin/gh-pages`
-- rebuilds only those published versions from tags
-- regenerates docs for the current workspace version
-- rebuilds the staged landing page index
-
-This does **not** rebuild docs for every historical `rclnodejs` tag. It only
-rebuilds the subset that is actually published online.
+- `--manifest <path>` — use a different version manifest
+- `--out <dir>` — stage into a different directory
 
 ## New Release Example
 
 For a new release such as `1.9.0`:
 
 1. Update `package.json` to `1.9.0`.
-2. Run `npm run docs`.
-3. Verify the local output in `docs/1.9.0/` and `docs/index.html`.
-4. Run `npm run docs:gh-pages`.
-5. Verify the staged output in:
-   - `build/gh-pages-docs/docs/1.9.0/`
-   - `build/gh-pages-docs/docs/index.html`
-   - `build/gh-pages-docs/.nojekyll`
-6. Publish the contents of `build/gh-pages-docs/` to the `gh-pages` branch.
+2. Add `1.9.0` to the `versions` array in `published-versions.json`.
+3. Run `npm run docs` to preview the new version locally (`docs/1.9.0/` and
+   `docs/index.html`).
+4. Cut and push the `1.9.0` release tag so `npm run docs:publish` can rebuild
+   it from Git.
+5. Run `npm run docs:publish`.
+6. Verify the staged output in:
+   - `build/published-docs/docs/1.9.0/`
+   - `build/published-docs/docs/index.html`
+   - `build/published-docs/.nojekyll`
+7. Publish the contents of `build/published-docs/` to GitHub Pages (the
+   `deploy-docs.yml` workflow does this automatically on a `docs-*` tag).
 
 ## GitHub Actions Deployment
 
@@ -82,11 +83,17 @@ so manual dispatches and `docs-*` tag pushes there will not run the docs build.
 
 ### What it does
 
-1. Full checkout with all tags and the `origin/gh-pages` branch.
-2. Runs `npm run docs:gh-pages` to stage the docs tree.
+1. Full checkout with all tags.
+2. Runs `npm run docs:publish` to stage the docs tree. This reads
+   `published-versions.json` and rebuilds every listed version from its tag.
 3. Uploads the staged output as a Pages artifact.
 4. Deploys to GitHub Pages (skipped when `dry_run` is `true`).
 
+The workflow only needs `contents: read` and never writes to any branch.
+Because the manifest plus the Git tags fully describe the published set, the
+live site is always reconstructed from a fresh build — nothing can silently
+drop off.
+
 ### Testing
 
 - Run the workflow manually with `dry_run` enabled first to verify the build
@@ -99,29 +106,29 @@ so manual dispatches and `docs-*` tag pushes there will not run the docs build.
 ## Manual Landing Page Rebuild
 
 If the staged docs tree already exists and you only want to rebuild
-`build/gh-pages-docs/docs/index.html`, run `tools/jsdoc/build-index.js` against
+`build/published-docs/docs/index.html`, run `tools/jsdoc/build-index.js` against
 that docs root and point it at the package metadata for the latest published
 version.
 
 Example for published version `1.8.0`:
 
 ```bash
-mkdir -p build/gh-pages-docs/.tmp
-git show 1.8.0:package.json > build/gh-pages-docs/.tmp/package-1.8.0.json
+mkdir -p build/published-docs/.tmp
+git show 1.8.0:package.json > build/published-docs/.tmp/package-1.8.0.json
 
-export RCLNODEJS_DOCS_ROOT="$PWD/build/gh-pages-docs/docs"
-export RCLNODEJS_DOCS_INDEX_PATH="$PWD/build/gh-pages-docs/docs/index.html"
+export RCLNODEJS_DOCS_ROOT="$PWD/build/published-docs/docs"
+export RCLNODEJS_DOCS_INDEX_PATH="$PWD/build/published-docs/docs/index.html"
 export RCLNODEJS_LOCAL_INDEX_PATH=''
-export RCLNODEJS_PACKAGE_JSON_PATH="$PWD/build/gh-pages-docs/.tmp/package-1.8.0.json"
+export RCLNODEJS_PACKAGE_JSON_PATH="$PWD/build/published-docs/.tmp/package-1.8.0.json"
 
 node tools/jsdoc/build-index.js
-rm -rf build/gh-pages-docs/.tmp
+rm -rf build/published-docs/.tmp
 ```
 
 ## Notes
 
-- The staged publish output keeps shared assets in `build/gh-pages-docs/docs/_static/`.
+- The staged publish output keeps shared assets in `build/published-docs/docs/_static/`.
 - `.nojekyll` must remain in the staged output because the published docs tree
   uses an underscore-prefixed directory.
-- The live docs index is the source of truth for which versions should remain
-  published.
+- `published-versions.json` is the source of truth for which versions are
+  published; the Git tags are the content source.

tools/jsdoc/published-versions.json

@@ -0,0 +1,35 @@
+{
+  "$comment": "Curated list of rclnodejs versions whose JSDoc is published to GitHub Pages. This file is the source of truth for the published set: add a version here when cutting its release. Each deploy rebuilds every listed version from its Git tag, plus the current package.json version from the workspace, so the live site is a pure function of this manifest and the tags.",
+  "versions": [
+    "0.12.0",
+    "0.13.0",
+    "0.14.0",
+    "0.14.1",
+    "0.15.0",
+    "0.15.2",
+    "0.16.0",
+    "0.17.0",
+    "0.18.0",
+    "0.20.0",
+    "0.21.3",
+    "0.22.3",
+    "0.26.0",
+    "0.28.0",
+    "0.29.0",
+    "0.30.0",
+    "0.31.0",
+    "0.32.0",
+    "0.33.0",
+    "1.0.0",
+    "1.1.0",
+    "1.2.0",
+    "1.3.0",
+    "1.5.0",
+    "1.6.0",
+    "1.7.0",
+    "1.8.0",
+    "1.9.0",
+    "2.0.0",
+    "2.1.0"
+  ]
+}