Skip to content

Docs → main on shared version-switcher CI (v0.7.0) - #93

Merged
coretl merged 31 commits into
mainfrom
docs-reusable-workflows
Jun 24, 2026
Merged

Docs → main on shared version-switcher CI (v0.7.0)#93
coretl merged 31 commits into
mainfrom
docs-reusable-workflows

Conversation

@coretl

@coretl coretl commented Jun 24, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Bring the new MyST docs onto main and cut docs CI over to the shared
myst-version-switcher-plugin reusable workflows at v0.7.0, in one merge.
This branch is docs + the CI swap, retargeted from docs to main — so merging
it lands the docs content and the new CI together, after which the docs branch
is retired and main is the single live docs version.

What changes

  • MyST docs → main (the 29 commits from docs): main now builds its own docs,
    so it is self-durable in the published site (_sources/main.zip) — no second branch,
    no shim.
  • ci.yml consumes the shared workflows:
    • docs: → docs.yml@v0.7.0, build-command: cp CONFIG.example CONFIG && make docs.
    • publish: → publish.yml@v0.7.0, version-name + guard-default-branch: "true"
      (every deploy asserts main is present, so a publish can never silently drop /main/).
    • triggers: pull_request + push to main + tags. docs-release (tag-only) attaches
      each release's docs.zip.
  • Deleted the old per-branch _docs.yml/_publish.yml (incl. the gh-pages main/
    shim and assemble@v0.5.0). Added preview-fork.yml (workflow_dispatch wrapper
    → publish.yml with pr) for the maintainer fork-PR preview opt-in.
  • code.yml and tests.yml unchanged.

Migration state (operator)

  • main was seeded durable up front via scripts/migrate.sh (pages-default-seed
    release → _sources/main.zip), so the guard passes pre-merge.
  • After merge, main builds the MyST docs itself and _sources/main.zip refreshes with
    real content; the seed becomes redundant.
  • Follow-up: delete the docs branch, then scripts/migrate.sh … --delete-gh-pages
    (drops gh-pages + the seed once _sources/main.zip is confirmed live).

First of the three docs repos (PandABlocks-server, then FPGA, then meta-panda).

🤖 Generated with Claude Code

coretl and others added 29 commits June 11, 2026 12:39
@coretl @claude
docs: Stage A scaffold
00f822c 
Instantiate the DLS python-copier-template MyST docs skeleton into
PandABlocks-server as a one-off scaffold (Stage A, runbook Prompt A).

- Move legacy Sphinx/RST tree to docs/_legacy_rst/ (ignored by myst build) so
  Stage D/E conversion can read sources in-tree; add docs/images/ with the logo.
- New myst.yml: title/github/logo swapped, server TOC + stubs for every v4 target
  page, empty tutorials.md landing for parity, Release Notes url.
- index.md README-include + how-to/contribute CONTRIBUTING-include resolve; add
  root README.md and .github/CONTRIBUTING.md.
- xref/intersphinx prototype: probe in reference/capture into PandABlocks-client
  resolves in built output; other repos commented until published.
- CI (.github/workflows/docs.yml) aligned with python-copier-template-example:
  npm+mystmd build, upload-artifact (docs/_build minus templates cache), versioned
  move, make_switcher.py, peaceiris v4; publish on main/tags; redirect -> main.
- docs/PROGRESS.md tracks Stage-A status.

myst build: green (exit 0, no warnings/errors), 18 pages, probe resolves.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@coretl @claude
docs: point commented FPGA xref at /main (was /master)
00e7a45 
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@coretl @claude
docs: convert reference/support.md from RST (Prompt D)
b81f6bc 
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
@coretl @claude
docs: Prompt D bulk conversion — all quadrants (PandABlocks-server)
3c5f76e 
Converts all writable-now Prompt D pages for the server repo:
- how-to/startup (from startup.rst)
- how-to/building (from building.rst; devcontainer pointer added; CONFIG syntax verify noted)
- reference/config (from config.rst)
- reference/streaming-tables (new; authored from Interview5 §8 + fields.rst)
- explanations/architecture (skeleton from server code)

Skipped per spec: commands/fields/capture/capture-options (Prompt E),
extension (blocked:verify), c-standard (blocked:author).
myst build green after each file.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
@coretl @claude
docs: convert commands, fields, capture; extract capture-options
4f4dcf6 
Prompt E (server hard files):
- reference/commands: full RST->MyST; Configuration + System command tables
  preserved, *IDN? kept, *CAPTURE.OPTIONS? cross-linked to capture-options.
- reference/fields: full conversion; MODE transition matrix and the
  Summary-of-Sub-Types / Summary-of-Attributes tables kept verbatim; streaming
  table-write detail points to reference/streaming-tables.
- reference/capture: keeps the ~60 MB/s figure + 'webcontrol not installed'
  caveat; Capture Options subsection extracted to reference/capture-options;
  links meta-panda how-to/integrate-with-a-panda for getting data out; retains
  the Stage A PandABlocks-client xref probe.
- reference/capture-options: field + connection options with the
  'run *CAPTURE.OPTIONS? live' note; superset remains blocked: verify.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@coretl @claude
docs: apply fresh-eyes review fixes (source-verified)
8816ea2 
- streaming-tables: correct MODE transition table (Reject rows, completed
  [HEALTH] row) and implicit-completed prose; B = plain base-64 with the
  left:right format moved to a new FIELDS entry; LENGTH/MAX_LENGTH in
  32-bit words
- fields: *CHANGES.PARAM -> *CHANGES.CONFIG (groups verified in
  config_server.h/system_command.c); drop nonexistent enum LABELS
  attribute; table length units; StdDev / Mean StdDev capture rows
- capture-options: make the canonical superset per pos_out.c (7 options,
  combinations, full curated enum list); caution downgraded to a note
- capture, commands: StdDev rows; add missing METADATA change group
- startup: duplicate -p -> -P pid-file; add -r rootfs-version (*IDN?)
- building: tip points at the in-repo devcontainer
- myst.yml: drop PandABlocks-devcontainer reference key (repo superseded
  by per-repo devcontainers)

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@coretl @claude
devcontainer: add ubuntu-devcontainer-based devcontainer
9c55c71 
Per-repo devcontainers replace the planned PandABlocks-devcontainer repo.
Modelled on python-copier-template (ubuntu-devcontainer:noble, developer
target) with C/Python build tools; the ARM cross-compiler is a candidate
addition for on-target builds.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@coretl @claude
ci: publish docs to gh-pages from the docs branch too
0e0edb7 
Trigger Docs CI on pushes to docs as well as main/tags, and allow the
gh-pages publish step on the docs branch so the rewritten docs deploy
before merging to main.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@coretl
docs: Stage B — link GitHub issues into stubs and verify notes
37c0ca0
@coretl @claude
docs: replace {doc} roles with markdown links
f607d07 
The {doc} role is not supported by MyST and emits a build warning for
every cross-reference (20 warnings across the reference and how-to pages).
Convert them to plain markdown links, which MyST resolves the same way.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@coretl @claude
devcontainer: update base image, add npm, and persistent caches
2e539da 
Bump the devcontainer base image to ubuntu-devcontainer:resolute and
install npm so the docs build can run mystmd via npx. Add persistent
uv/pre-commit caches, a shared cache volume, and refresh the VS Code
extensions and settings.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@coretl @claude
docs: migrate to MyST build and published version-switcher plugin
5bfb940 
Replace the local _plugins prototype and make_switcher.py with the
published DiamondLightSource/myst-version-switcher-plugin (v0.2.0): the
release-asset module renders the {version-switcher} navbar dropdown, and
the switcher composite action writes switcher.json plus the root redirect
into the gh-pages publish tree.

Build the docs with mystmd instead of Sphinx. 'make docs' / 'make docs-dev'
run myst through npx, pinned by MYSTMD_VERSION in CONFIG, and stage output
for the zpkg packaging. docs.yml mirrors the plugin repo's _docs.yml as a
non-reusable workflow, staging into RUNNER_TEMP rather than an in-repo
.github/pages directory.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@coretl @claude
docs: output page URLs by folder name
9442cc7 
Set site.options.folders so pages are served under their folder, e.g.
/reference/commands and /how-to/startup, instead of the default flattened
/commands and /startup.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@coretl @claude
docs: document interim /docs xref target and stable plan
9ff317d 
Record the cross-repo inventory plan where the references live. The MyST
repos point at each repo's docs-branch build (<repo>/docs/objects.inv) for
now, switching to <repo>/stable once the upstream version-switcher action
(in a separate repo) publishes a stable symlink to the latest release;
Pages tars with --dereference, so the symlink materialises as long as its
target version is retained. PandABlocks-client (Sphinx, released) stays on
its deployed /main path. Switch the commented prototype URLs to the interim
/docs form so they are ready to uncomment.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@coretl @claude
docs: convert meta-panda links to xrefs
056e4b7 
meta-panda's MyST docs-branch build is live, so activate its reference and
replace the two hardcoded meta-panda doc-page URLs with path-based xrefs:
- tutorials.md            -> xref:meta-panda/tutorials
- reference/capture.md    -> xref:meta-panda/integrate-with-a-panda

MyST resolves these via meta-panda's myst.xref.json (path form, since pages
carry no #identifier), and they repoint automatically when the base moves
/docs -> /stable. All cross-repo doc links in this repo are now xrefs.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@coretl @claude
docs: enable PandABlocks-FPGA xref and fix meta-panda xref path
536f1ed 
- myst.yml: uncomment the PandABlocks-FPGA xref reference (interim /docs
  target). folders is already enabled here.
- reference/capture.md: update the meta-panda xref to the folder-qualified
  path (how-to/integrate-with-a-panda) now that meta-panda emits folder URLs.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@coretl
Merge pull request #86 from PandABlocks/migrate-version-switcher
2433959 
Migrate version switcher
@coretl @claude
docs: build with myst --strict
d89ea5b 
`make docs` now runs `myst build --html --strict`, so CI exits non-zero on
any error-severity message (e.g. an unresolved cross-repo xref) rather than
publishing broken links. Verified the docs build clean at exit 0 under --strict.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@coretl @claude
docs: enforce link quality via error_rules
0a1666c 
Escalate link-resolves, reference-target-resolves and link-text-exists to
error so (with `make docs` / `myst build --strict`) broken links, unresolved
cross references and empty auto-filled labels fail CI. See
reference/documentation-standards in meta-panda for the conventions enforced.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@adedamola-sode
removed AI comment as command still works
50eb3ec
@adedamola-sode
Merge pull request #89 from PandABlocks/IDN
eb6a1aa 
removed AI comment as command still works
@coretl @claude
Docs: migrate to myst-version-switcher assemble model (v0.5.0)
71cebb1 
Replace the legacy peaceiris/actions-gh-pages + keep_files publish (and the
old switcher@v0.2.0 action) with the version-switcher assemble model:

- ci.yml + _docs.yml + _publish.yml (the documented tutorial split). _docs.yml
  keeps `make docs` (npx mystmd) and now packs docs.zip (bare html/ root);
  _publish.yml runs assemble@v0.5.0 -> upload-pages-artifact -> deploy-pages.
- Bump the version-switcher plugin v0.2.0 -> v0.5.0 in docs/myst.yml.
- Publish the `docs` branch as the live version during migration
  (guard-default-branch: false; main has no MyST docs yet).
- Remove the old docs.yml.

The Pages-source flip + gh-pages backfill/delete are a separate cutover.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@coretl
Merge pull request #91 from PandABlocks/docs-version-switcher-assemble
45c5395 
Docs: migrate versioned-docs publishing to myst-version-switcher assemble model (v0.5.0)
@adedamola-sode
changed documentation from sphinx to mystmd
4756555
@adedamola-sode
adding node to CI container for building docs during zpkg build
6caa79d
@adedamola-sode
Removed rootfs kernel and zpkg
bd5fb6f
@coretl @claude
Docs: re-deploy docs version after closing the docs->main preview race
cde459c 
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@coretl @claude
Docs: overlay legacy main/ from gh-pages during migration
7b19bb3 
main has no MyST docs build yet, so the assemble model drops /main/. Until
docs merges to main, stage the existing gh-pages main/ build into the assemble
site dir so generate lists main in switcher.json and /main/ keeps serving.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@coretl @claude
Docs: verify the deployed Pages origin matches the assembled switcher…
6b55daa 
….json

Mirror the upstream myst-version-switcher _publish.yml change: after deploy-pages,
poll the live switcher.json and fail if it does not byte-match the assembled one,
so a stale/wedged Pages origin surfaces as a red check instead of silently
serving old docs.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@coretl
coretl force-pushed the docs-reusable-workflows branch from a31ffd8 to 4bee191 Compare June 24, 2026 15:07
@coretl
coretl force-pushed the docs-reusable-workflows branch from 4bee191 to f9f2aad Compare June 24, 2026 15:46
@coretl coretl changed the title Docs CI: consume shared reusable workflows @v0.7.0 Docs → main on shared version-switcher CI (v0.7.0) Jun 24, 2026
@coretl
coretl changed the base branch from docs to main June 24, 2026 15:47
@coretl @claude
Docs CI: consume shared reusable workflows @v0.7.0
69e1499 
Replace this repo's docs-build/publish workflows with calls to the shared
myst-version-switcher-plugin reusable workflows pinned at v0.7.0:

- docs.yml@v0.7.0 builds with `cp CONFIG.example CONFIG && make docs`
- publish.yml@v0.7.0 reconstructs the whole versioned site from durable
  sources (main's build persisted at _sources/main.zip, release docs.zip
  assets, open-PR artifacts) and deploys to Pages directly (no gh-pages)

main is the docs branch and the default branch, so it is self-durable and
guard-default-branch stays "true": every deploy asserts main is present, so a
publish can never silently drop /main/.

Delete the old per-branch _docs.yml/_publish.yml (incl. the gh-pages main shim
and assemble@v0.5.0). Add preview-fork.yml, a workflow_dispatch wrapper calling
publish.yml with `pr` (a reusable workflow can't be dispatched cross-repo) for
the maintainer fork-PR preview opt-in; docs.yml's fork warning links to it.

code.yml and tests.yml are unchanged.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RBtsHDzshkwFgTJtrDVveU
@coretl
coretl force-pushed the docs-reusable-workflows branch from f9f2aad to 69e1499 Compare June 24, 2026 15:50
@coretl @claude
docs: pin favicon to the PandA logo + set logo_text
be4ad7a 
The docs set no favicon, so `myst build` fetched MyST's default favicon from
mystmd.org on every build; when that remote fetch flakes ("Premature close")
the build fails (exit 2). Pin the favicon to the bundled PandA logo so the
build is self-contained, and set logo_text to the repo name.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RBtsHDzshkwFgTJtrDVveU
@coretl
coretl merged commit b327fbc into main Jun 24, 2026
7 of 11 checks passed
@coretl
coretl deleted the docs-reusable-workflows branch June 24, 2026 16:18
@coretl coretl mentioned this pull request Jun 29, 2026
Merged
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@coretl @adedamola-sode