[Docs] Rebuild JSDoc site as a pure function of manifest + git tags#1553
Merged
Conversation
There was a problem hiding this comment.
Pull request overview
This PR refactors the JSDoc publishing pipeline to be fully reproducible (stateless) by rebuilding the entire GitHub Pages site from a curated versions manifest plus Git release tags, rather than relying on (and mutating) a cached gh-pages branch.
Changes:
- Introduces
tools/jsdoc/published-versions.jsonas the single source of truth for which versions are published. - Rewrites
tools/jsdoc/regenerate-published-docs.jsto always rebuild the full published docs tree from tags + current workspace (nogh-pagessnapshot/cache logic). - Updates the Pages workflow and npm scripts to use the new
docs:publishpath and artifact directory.
Reviewed changes
Copilot reviewed 5 out of 5 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
| tools/jsdoc/regenerate-published-docs.js | Switches to manifest-driven stateless rebuild using git tags/worktrees and a new default output directory. |
| tools/jsdoc/README.md | Updates docs to describe the manifest + tags model and new docs:publish command/flags. |
| tools/jsdoc/published-versions.json | Adds curated list of versions to publish (manifest). |
| package.json | Replaces docs:gh-pages* scripts with docs:publish. |
| .github/workflows/deploy-docs.yml | Removes gh-pages fetch/write-back and uploads build/published-docs to Pages. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
42
to
46
| options.outputRoot = path.resolve(argv[index + 1]); | ||
| index += 1; | ||
| } else if (arg === '--versions') { | ||
| options.versions = argv[index + 1] | ||
| .split(',') | ||
| .map((value) => value.trim()) | ||
| .filter(Boolean); | ||
| } else if (arg === '--manifest') { | ||
| options.manifestPath = path.resolve(argv[index + 1]); | ||
| index += 1; |
Comment on lines
+35
to
+37
| - reads the published version set from `published-versions.json` | ||
| - rebuilds every listed version from its Git tag | ||
| - rebuilds the current workspace version from the working tree (always included) |
|
coverage: 91.103% (-0.04%) from 91.143% — minggangw:fix-1552 into RobotWebTools:develop |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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.
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).docs:gh-pages/docs:gh-pages:fullwith a singledocs:publishscript.contents: read, remove the gh-pages fetch and write-back steps, runnpm run docs:publish, and upload build/published-docs as the Pages artifact.Fix: #1552