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>
Contributor
|
I would like to mention that the instructions to update the panda are for a new yocto rootfs, for the old rootfs, you need to also remove the old rootfs files, in particular, it is important to remove the conflicting files: uImage, uinitramfs and devicetree.db. |
…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
This is to fix conflics in a PR
removed webcontrol requirement for pre 5.0 upgrading of panda in upgrade-via-ssh. Added ssh requirement
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>
separated working in a container from the build page
Contributor
Author
|
Closing during the versioned-docs migration to myst-version-switcher. The Closing removes that race. Re-open / recreate this PR when the docs work is ready to actually merge into the default branch (at which point the default branch becomes the live version). Tracked in the docs-migration issue. |
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.
No description provided.