Add versioned release and pre-release doc publishing workflows#1164
Conversation
- Introduced `docs_pre_release.yml` for publishing pre-release documentation on pushes to the `pre-release` branch. - Added `docs_release.yml` for publishing release documentation on tag pushes and manual dispatch. - Removed inline documentation generation from CI workflow to streamline processes. - Updated documentation configuration to support version switching and improved UI elements in the documentation layout. - Implemented a new script `docs_publish.py` for managing the documentation publishing process.
There was a problem hiding this comment.
Pull request overview
This PR introduces versioned documentation publishing to GitHub Pages so release docs are retained per tag, a /latest/ alias points to the newest release, and /pre-release/ publishes development docs. It also updates the Sphinx theme customization to add a docs version selector and version-status banners, and adds repo-local rollout/implementation planning docs.
Changes:
- Added dedicated GitHub Actions workflows for release-tag docs publishing and
pre-releasebranch docs publishing. - Added
scripts/docs_publish.pyto write versioned docs trees plus sharedversions.json, a/versions/index page, and an optional root redirect. - Updated Sphinx template/static assets to fetch
versions.json, render a version selector, and show version-status banners.
Reviewed changes
Copilot reviewed 12 out of 12 changed files in this pull request and generated 5 comments.
Show a summary per file
| File | Description |
|---|---|
scripts/docs_publish.py |
New publisher script to sync versioned docs trees and generate versions.json + versions index page (+ optional root redirect). |
docs/src/conf.py |
Injects docs publishing context into Sphinx HTML templates via env vars. |
docs/src/_templates/layout.html |
Adds version switcher container and exposes config into window.ROGUE_DOCS. |
docs/src/_static/custom.js |
Adds client-side versions metadata fetching, version selector behavior, and banners. |
docs/src/_static/custom.css |
Styles for the selector UI and banners. |
docs/README.md |
Notes location of the new planning documents. |
docs/plans/versioned-docs-rollout.md |
Rollout plan for safe deployment of versioned docs. |
docs/plans/versioned-docs-implementation.md |
Architecture/implementation plan for versioned docs. |
docs/plans/README.md |
Index for documentation planning docs. |
.github/workflows/rogue_ci.yml |
Removes tag-triggered docs publishing from the main CI workflow. |
.github/workflows/docs_release.yml |
New release docs publishing workflow (tag + manual staging). |
.github/workflows/docs_pre_release.yml |
New pre-release branch docs publishing workflow. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
|
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## pre-release #1164 +/- ##
============================================
Coverage 54.51% 54.51%
============================================
Files 70 70
Lines 7862 7862
Branches 1179 1179
============================================
Hits 4286 4286
Misses 3300 3300
Partials 276 276 ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
|
@bengineerd I think this. OpenFPGA does a similar thing on their github.io as well |
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 11 out of 11 changed files in this pull request and generated 5 comments.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 12 out of 12 changed files in this pull request and generated 7 comments.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 12 out of 12 changed files in this pull request and generated 1 comment.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Description
Add versioned documentation publishing on GitHub Pages so release docs can be retained per tag, expose a
latestalias for the newest release, and publish development docs frompre-release.Details
This change:
versions.json, a versions index page, and thelatestaliasdocs/plans/Related
/staging-docs/before production release publishing is exercised