Republish docs
Republish or revise the Read the Docs pages for an ALREADY-RELEASED SUEWS version without cutting a new code release. Use when /stable/ (or a numbered /X.Y.Z/) shows a "Development Version" banner, a stale .dev schema label, or any doc fix that must reach a published release. Fixes docs on master, lets docs-sync refresh the rtd branch, runs the release-docs-anchor workflow to rebuild a banner-free anchor and move the tag, then verifies.From its SKILL.md
npx -y skills add UMEP-dev/SUEWS --skill republish-docsAssembled from the repository path, not quoted from the project. Check it against their README if it does not work.
SKILL.md
6.1 KB, as published. Nobody here has run it
Republish / revise released docs
Drive a documentation fix onto an already-released SUEWS version's Read the
Docs pages (/stable/ and the numbered /X.Y.Z/) without cutting a new code
release. The published release tag is moved onto a freshly-built, banner-free
docs anchor commit; PyPI and Zenodo are untouched.
When to use
/stable/shows a "Development Version" banner (it was pointed at HTML built with a.devversion).- A published release's docs cite a stale
.devschema label (e.g.2026.5.dev7) or need a prose/typo fix. - Any doc change that should reach an already-shipped release, not just
latest.
When NOT to use
- Cutting a brand-new release -> use
prep-release(it already calls the same anchor step at step 11a). - Doc-vs-code content consistency -> use
sync-docs. - RST / Markdown formatting / ASCII -> use
lint-code/audit-docs.
Background (how docs are served)
latestcomes from thertdbranch:docs-sync.ymlmergesmasterintortd, builds the HTML withSUEWS_DOCS_VERSION_REF=origin/master(a.devversion, so the banner is present and CORRECT there), and commits the pre-built HTML for RTD to copy.stableand numberedX.Y.Zcome from the release tag, which must sit on an off-master docs anchor commit whose HTML was built withSUEWS_DOCS_VERSION_REF=<tag>-> the version resolves clean -> no banner.release-docs-anchor.ymlbuilds that anchor and moves the tag.
See dev-ref/RELEASE_MANUAL.md ("Documentation on Read the Docs") and
.claude/rules/docs/release-docs-sanity.md.
Procedure
1. Fix the docs on master (PR)
Make the content fix on a normal branch and merge to master, so latest and
all future releases inherit it. Include, where the change touches schema labels:
- Regenerate the committed schema artefact (it is NOT refreshed by
make generate-rst):suews schema export -o docs/source/inputs/tables/schema.json # or: python -m supy.cmd.schema_cli export -o docs/source/inputs/tables/schema.json - Run the stray-dev-label scan from
.claude/rules/docs/release-docs-sanity.md(keep legitimate "collapsing dev1..dev14" narration; fix only labels presented as a current user-facing schema version).
2. Let docs-sync refresh the rtd branch
After the PR merges, docs-sync.yml runs automatically. Wait for it, then
confirm the fix reached rtd (the anchor builds FROM rtd):
gh run list --repo UMEP-dev/SUEWS --workflow docs-sync.yml --limit 1 \
--json status,conclusion
git fetch origin rtd
git show origin/rtd:docs/source/inputs/tables/schema.json | grep -c "<stale-label>" # want 0
3. Dispatch the anchor workflow
gh workflow run release-docs-anchor.yml -f release_tag=<X.Y.Z> --repo UMEP-dev/SUEWS
It checks out rtd, asserts the tag resolves to a clean version, does a FULL
clean rebuild (rm -rf build + -E -a), asserts the banner is absent, commits
an off-master anchor, and force-moves <X.Y.Z> onto it (pushing only the tag).
4. Monitor + verify the anchor
gh run watch <run-id> --repo UMEP-dev/SUEWS --exit-status
git fetch origin "refs/tags/<X.Y.Z>:refs/tags/<X.Y.Z>" --force
git ls-remote --tags origin <X.Y.Z> # tag now points at the new anchor SHA
# the anchor's committed HTML is the source of truth (independent of RTD caching):
git show <X.Y.Z>:docs/build/html/inputs/forcing-data.html \
| grep -c "built from a development version" # want 0
5. Verify the live site after RTD rebuilds
RTD rebuilds asynchronously (a few minutes after the tag moves). Poll:
curl -fsSL https://docs.suews.io/stable/inputs/forcing-data.html \
| grep -c "built from a development version" # want 0
Gotchas (all hit on the first real run; the workflow now guards them)
- Banner grep must be banner-specific. Grep
built from a development version(onlydocs/source/conf.py's announcement emits it), NOT the bare phraseDevelopment Version-- that legitimately appears ininstallation.rst(TestPyPI dev builds) andsearchindex.js, causing false positives. - The anchor build must be a FULL clean rebuild. The
rtdbranch ships pre-built HTML carrying the.devbanner on every page. An incrementalsphinx-buildonly re-renders changed pages, leaving unchanged pages with the stale banner. The.dev-> clean version flip is a theme-level change that does not invalidate per-page doctrees, so the workflow doesrm -rf buildand passes-E -a. - Never point a release tag at the
rtdbranch HEAD directly -- its HTML was built with the.devversion and carries the banner. Always go throughrelease-docs-anchor.yml. - The numbered
/X.Y.Z/RTD version needs a MANUAL rebuild. A tag force-move does not re-trigger the numbered version's build on RTD (RTD keys on the version name, which is unchanged).stablerebuilds automatically, but/X.Y.Z/keeps its old cached build until someone clicks Versions -> X.Y.Z -> Build version in the RTD dashboard. This step is human-only (no RTD-platform token in CI); surface it to the maintainer.
References
.github/workflows/release-docs-anchor.yml-- the automation this skill drives..github/workflows/docs-sync.yml-- the rollinglatestbuild (banner expected there)..claude/rules/docs/release-docs-sanity.md-- the release-time docs sanity check..claude/rules/python/schema-versioning.md-- schema-label collapse rules.dev-ref/RELEASE_MANUAL.md-- "Documentation on Read the Docs (release docs & revisions)"..claude/skills/prep-release/SKILL.md-- at-release-time path (step 11a calls the same anchor workflow).