Docs→main: consolidate CI, adopt version-switcher v0.23.0 - #37
Open
coretl wants to merge 63 commits into
Open
Conversation
Inventories all .rst and .md files under docs/ in PandABlocks-FPGA, PandABlocks-server, PandABlocks-rootfs, PandABlocks.github.io, and meta-panda, with word counts, last-commit dates, one-line summaries, audience notes, and an outdated/partial/current status flag. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Cross-repo analysis of duplications, gaps, and open questions based on the current/partial docs in knowledge/01-inventory.md. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Instantiate the DLS python-copier-template MyST docs skeleton into meta-panda as
a one-off scaffold (Stage A, runbook Prompt A). Building, complete-but-empty docs
tree; no content conversion yet.
- Move the legacy Sphinx/RST tree to docs/_legacy_rst/ (ignored by myst build) so
Stage D/E conversion can read the cited sources in-tree; keep docs/images/.
- New myst.yml: title/github/logo swapped (PandA logo), meta-panda TOC + page stubs
for every v4 target page, Release Notes url kept.
- Drop apidoc plugins block, reference/api.{md,json}, tutorials/installation.md,
how-to/run-container.md (skeleton Python-only artifacts).
- index.md README-include and how-to/contribute CONTRIBUTING-include both resolve;
add root README.md and .github/CONTRIBUTING.md.
- xref/intersphinx prototype in myst.yml project.references; probe link into the
PandABlocks-client Sphinx repo resolves in built output. Other core repos +
devcontainer + fastcs kept commented until their docs publish.
- docs/PROGRESS.md tracks Stage-A items and per-page status.
myst build: green (exit 0, no warnings/errors).
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Switch the Pages workflow to the new MyST docs: - ubuntu-latest runner; install mystmd (pinned 1.10.1) via npm - myst build --html in docs/ with BASE_URL=/meta-panda/<version> so links/assets resolve under the versioned GitHub Pages sub-path - copy docs/_build/html into .github/pages/<version>/ and publish to gh-pages with the same pinned peaceiris action + keep_files (preserves the catch-all redirect) - publish stays gated to rel-* branches and tags under the PandABlocks org Validated locally: green build, BASE_URL applied to asset paths, versioned-dir copy and redirect intact. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
…tifact Model .github/workflows/docs.yml on the python-copier-template-example _docs.yml: - checkout@v5 (fetch-depth 0); sanitize GITHUB_REF_NAME into DOCS_VERSION - upload-artifact@v4 of docs/_build as the 'docs' artifact (zipped) - move build to versioned .github/pages/<version>/; generate switcher.json via make_switcher.py (copied from the template) - publish via peaceiris v4.0.0 (pinned SHA), keep_files: true Root branch moved rel-* -> main: - publish gated on github.ref_name == 'main' || ref_type == 'tag' - .github/pages/index.html redirects to ./main/index.html Adaptations from the template (documented in PROGRESS.md): - build with npm + mystmd (myst build --html) rather than uv/tox: meta-panda is a Yocto layer, not a Python/uv project - keep BASE_URL=/meta-panda/<version> so assets resolve under the versioned Pages sub-path (template's mystmd migration doesn't set it yet) Validated locally end-to-end with DOCS_VERSION=main: green build, BASE_URL applied, artifact path populated, versioned move, switcher.json generated. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Restrict push triggers to main + tags (mirroring python-copier-template-example ci.yml on: block) so a feature-branch PR fires a single pull_request run instead of both a push and a pull_request run. No reusable-workflow nesting. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
The artifact uploaded the whole docs/_build, which includes the ~135 MB templates/ dir (downloaded book-theme node sources) plus cache/ and site/ — build-time only, nothing deployable. Upload docs/_build/html instead, cutting the zipped artifact ~7x (measured 49 MB -> 7 MB). The remaining size is the mystmd client runtime (plotly + thebe + React chunks), inherent to a mystmd static site. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Uploading docs/_build/html put the site contents flat at the artifact root, losing the intermediate html/ directory the original docs.zip had. Restore docs/_build as the upload root (so html/ is retained) and instead rm the ~135 MB templates/ build cache beforehand. Same ~7 MB result, original layout. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Convert three tutorial RST sources to MyST Markdown. tutorial0 rewrites the MalcolmJS quick-start for PandA web control context; tutorial1 and tutorial2 are straightforward RST→MyST conversions with timing diagrams described inline (the custom timing_plot directive replaced with ASCII art + prose). Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Convert all writable how-to pages from RST to MyST Markdown. Includes: - quickstart: merged with rootfs source, fixed boot.txt→config.txt, FAQ moved to reference/troubleshooting - build: merged kas + docker approaches; KAS_IMAGE_VERSION verify note - manual-build: fixed Xilinx manifest URL to Xilinx/yocto-manifests - make-release: releases link fixed to meta-panda repo - packages, upgrade-via-ssh, upgrade-via-web-admin, monitor-attribute-values - Three NEW authored pages: integrate-with-a-panda, test-firmware-changes, choose-fpga-bitstream (from Interview3/5 knowledge) - contribute: xref/intersphinx setup documented; CONTRIBUTING.md include kept Skipped (Prompt E): use-web-control-to-set-up-a-panda, save-restore-design Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
… troubleshooting)
- opkg: RST→MyST quick-reference table
- machine-targets: NEW from Interview6; MACHINE table with PandABrick verify note
- glossary: canonical merge of webcontrol + FPGA glossaries using MyST {glossary}
directive; Zpkg entry notes legacy status (pre-5.0)
- troubleshooting: seeded from quickstart.rst FAQ (7 Qs); boot.txt→config.txt fixed
- reference/changes left as stub (blocked: verify — 3.0→4.0 absent)
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
- boot-process: RST→MyST; numbered stages + key-files table - architecture: NEW skeleton from Interview1; layers diagram + data-flow ASCII art - web-control-ui-overview: RST→MyST from user_interface_overview.rst; all screenshots reused in-place from _legacy_rst - understanding-attribute-state: 8 states converted; 5 existing PNG icons referenced from _legacy_rst; Processing/Update-Error/Invalid marked as pending Prompt C SVGs (docs/images/attribute-state/) Skipped (blocked/done): hardware-targets (blocked: author), decisions (✅ from Stage A) Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
…re-design Split webcontrol/userguide/working_with_a_design.rst (Prompt E) into: - how-to/use-web-control-to-set-up-a-panda (the bulk; attribute widgets folded in) - how-to/save-restore-design (Saving a Design + Opening an Existing Design) The four attribute-widget subsections (View/Edit, Dropdown, Text Input, Checkbox) and the truncated trailing sentence are kept as a blocked: capture stub with its issue placeholder, pending new screenshots. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
The {glossary} directive requires definition-list children: each term on its
own line followed by a ': ' definition. The page used RST-style indented
definitions (no colon), so no terms registered and every {term} reference
failed repo-wide (32 'Unexpected node as a child of a glossary' errors). Convert
all entries to the colon form and fix the stale {term}`Layout View` reference
in web-control-ui-overview (the term is 'Layout').
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
- README: add PandABlocks-level framing before the Yocto-layer intro - myst.yml: band the how-to TOC (use / administer / develop) - machine-targets: ground-truth against conf/machine/ (drop xu5-s1, add pandabox2); mark xu5-st1/zedboard development-only - web-control pages: trim to live UI (port colours Boolean/Int32 only, single Save method, "Design Name" field); copy 19 images out of _legacy_rst into docs/images/webcontrol/ and repoint all references - upgrade-via-ssh: Image -> image.ub; integrate: fix opkg link - tutorial 1: CLOCKS -> CLOCK1; tutorials: quickstart signposts - glossary: App entry leads with .ipk, zpkg demoted to legacy - understanding-attribute-state: replace runbook jargon placeholders Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Per-repo devcontainers replace the planned PandABlocks-devcontainer repo. Modelled on python-copier-template, but kas-based (ghcr.io/siemens/kas/kas:4.8, matching KAS_IMAGE_VERSION in build.sh) since this repo builds with bitbake. Lives entirely under .devcontainer/ as the root Dockerfile is the existing FPGA-tools/CI container. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
create-issues.sh files the remaining human-verification issues (run with an authenticated gh; it commits its own marker edits). 09-fresh-eyes-review.md records what was fixed and the user-confirmed answers; runbook annotated where the per-repo devcontainer decision superseded it. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
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>
Issues created for all human-capture, verify-then-write, author-from-scratch, and infrastructure backlog items (see PROGRESS.md Blocked section).
Recreate the eight attribute-state glyphs as standalone material-style SVGs under docs/images/attribute-state/, in the colour spec derived from the web control theme, and wire them into explanations/understanding-attribute-state. Replaces the three pending placeholders and the five PNGs with a consistent SVG set. No external UI toolkit is referenced in the docs. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
…', combining some parts of quickstart and old tut 0
Getting started
- myst.yml: enable folder-qualified page URLs (site.options.folders: true) and turn on the PandABlocks-FPGA / PandABlocks-server xref references (interim /docs targets; -> /stable later). - Convert cross-project http links to xref: the PandABlocks-server commands reference and the PandABlocks-client landing-page links. Cross-repo inventories only resolve once each repo's docs branch is pushed with folders enabled. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Replace Sphinx `{doc}` cross-references with native MyST markdown links
([](path.md)) for intra-repo page links across tutorials, how-to,
explanations and reference pages.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
# Conflicts: # docs/how-to/setup-without-dhcp.md # docs/how-to/test-firmware-changes.md # docs/how-to/upgrade-via-ssh.md # docs/tutorials/blinking_leds.md # docs/tutorials/connecting_to_web_control.md # docs/tutorials/position_capture.md
The docs restructure renamed several pages but left dangling references:
- how-to/quickstart -> how-to/setup-without-dhcp (toc + 4 links)
- tutorials/tutorial2_position_capture -> tutorials/position_capture
- {doc}`tutorial3_position_compare` -> {doc}`position_compare`
- {doc}`tutorial_blinking_leds` -> {doc}`blinking_leds`
- getting_started "next steps" link pointed at how-to/ instead of tutorials/
All internal .md and {doc} links in docs now resolve.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
- Convert the 7 remaining {doc} roles to markdown links (the tutorial pages
reintroduced them via the merge, plus how-to/test-firmware-changes).
- docs.yml: build with `myst build --html --strict` so CI exits non-zero on
any error-severity message (e.g. an unresolved cross-repo xref).
Verified the docs build clean at exit 0 under --strict.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
- myst.yml: escalate link-resolves, reference-target-resolves and link-text-exists to error so (with --strict) broken links, unresolved cross references and empty auto-filled labels fail CI. - Add reference/documentation-standards.md describing the linking conventions these rules enforce (page/section/explicit targets, internal vs xref, path rules, empty-label inheritance), and list it in the toc. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Move the cross-repo reference-target table and config note out of the contribute how-to into reference/documentation-standards (new "Configured cross-repo targets" section), and reduce the how-to to a pointer that links to the reference. Also corrects the stale "FPGA/server are commented out" note — those references are now enabled; only fastcs-PandABlocks remains commented. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Replace the legacy peaceiris/actions-gh-pages + keep_files publish (and the
in-repo make_switcher.py) with the version-switcher assemble model, and adopt
the shared `make docs` build used by the other PandABlocks repos:
- ci.yml + _docs.yml + _publish.yml (the documented tutorial split). _docs.yml
drives the build through `make docs` (npx mystmd, pinned by MYSTMD_VERSION in
CONFIG) and packs docs.zip (bare html/ root); _publish.yml runs assemble@v0.5.0
-> upload-pages-artifact -> deploy-pages.
- Add a minimal Makefile + CONFIG.example (the repo had none) exposing the same
`make docs` target; gitignore the local CONFIG copy.
- .devcontainer/Dockerfile (kas-based): add make + npm so `make docs` works in
the container.
- docs/myst.yml: add the version-switcher plugin v0.5.0; add navbar_end.md.
- 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 and .github/pages/{make_switcher.py,index.html}.
The Pages-source flip + gh-pages backfill/delete are a separate cutover.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
separated working in a container from the build page
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>
Docs: migrate versioned-docs publishing to myst-version-switcher assemble model (v0.5.0)
….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>
Checkpoint of the in-progress consolidation before rebasing docs onto main: folds code.yml into ci.yml, and (per the docs -> main pivot used by PandABlocks-server/FPGA) drops the now-obsolete docs and rel-* branch triggers so main + tags is the only trigger surface. Also points the PandABlocks-server/FPGA cross-repo doc refs at main and bumps the version-switcher plugin pin to v0.22.0.
layer's default branch (no overlapping files; same docs -> main pivot used by PandABlocks-server #93 and PandABlocks-FPGA #289).
…op the GitLab-covered boot build Replace the local _docs.yml/_publish.yml/_release.yml (assemble@v0.5.0 model) with the shared docs.yml/publish.yml/release.yml@v0.22.0 reusable workflows, plus the publish-dispatch.yml shim -- the same recipe already used by PandABlocks-server and PandABlocks-FPGA. Drop the make_boot job and _make_boot.yml: .gitlab-ci.yml's build/release-all jobs already build the Yocto boot images and release them (on GitLab, via Diamond's pollux-dev runners), so the self-hosted iris_runners GitHub build was redundant.
…ge workflows v0.23.0 carries the publish.yml stable-alias fix meta-panda's mid-migration state (no MyST-released tag yet) would otherwise hit. _make_sdk.yml and _make_image.yml were unreferenced by any workflow (dead since before this consolidation) -- deleted rather than left as clutter.
EmilioPeJu
approved these changes
Jul 6, 2026
EmilioPeJu
left a comment
EmilioPeJu
left a comment
Contributor
There was a problem hiding this comment.
Documentation looks good (I added just a couple of corrections)
| |---|---|---| | ||
| | Direct TCP | — | Low-level scripting, quick checks | | ||
| | Python client | [PandABlocks-client](xref:PandABlocks-client) | Python applications; preferred for new integrations | | ||
| | EPICS / Tango | [fastcs-PandABlocks](https://github.com/DiamondLightSource/fastcs-PandABlocks) | Control-system integrations | |
Contributor
There was a problem hiding this comment.
This URL seems to have moved to https://github.com/PandABlocks/fastcs-PandABlocks
| To target a different machine set `KAS_MACHINE`, e.g.: | ||
|
|
||
| ```bash | ||
| KAS_MACHINE=xu5-st1 kas-container build ./kas.yml |
Contributor
There was a problem hiding this comment.
xu5-st1 machine is now called xu5 (matching the FPGA target renaming)
| | `zedboard` | Zedboard | Development/testing platform | | ||
|
|
||
| The generally supported machines are `pandabox`, `pandabox2` and `pandabrick`; | ||
| `xu5-st1` and `zedboard` are development-only targets. |
Contributor
There was a problem hiding this comment.
as mentioned earlier xu5-st1 was renamed to xu5
|
|
||
| ## FPGA bitstream | ||
|
|
||
| ### How do I override the FPGA bitstream variant used? |
Contributor
There was a problem hiding this comment.
Given this information is already in a how-to guide, maybe we should remove this question from here to avoid redundancy?
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
4 participants
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.
Summary
docsbranch's MyST docs migration ontomain(no file overlap:mainhad only Yocto-layer/.gitlab-ci.ymlchanges since the branches diverged).myst-version-switcher-pluginreusable workflows at v0.23.0 (replacing the local_docs.yml/_publish.yml/_release.yml, which consumed the olderassemble@v0.5.0action), following the same recipe already used by PandABlocks-server and PandABlocks-FPGA.docs/rel-*branch triggers — CI now runs onmain+ tags only.make_bootjob/_make_boot.yml(self-hostediris_runners):.gitlab-ci.yml'sbuild/release-alljobs already build and release the same Yocto boot images on Diamond'spollux-devrunners, so the GitHub-side build was redundant. The GitHubreleasejob (viarelease.yml@v0.23.0) now exists solely to attachdocs.zipto a GitHub Release for the version-switcher's release backfill._make_sdk.yml/_make_image.ymlworkflows (unreferenced by any trigger).PandABlocks-server/PandABlocks-FPGAcross-repo doc xrefs to theirmainbranch (both have completed or are completing the same docs→main pivot).Migration state
scripts/migrate.sh PandABlocks/meta-panda(prepare step) has been run: releases backfilled,mainseeded (pages-default-seedrelease) so the first publish from this PR's CI has a durable source to persist, and Pages is now served from GitHub Actions (gh-pages retained as the instant rollback).Test plan
make docs(strict) builds clean locally — 39 pages, exit 0main's first publish deploys and_sources/main.zipgoes live, then finalize withscripts/migrate.sh PandABlocks/meta-panda --delete-gh-pages🤖 Generated with Claude Code