PandABlocks · coretl · Jun 8, 2026 · Jun 8, 2026 · Jun 8, 2026 · Jun 11, 2026
diff --git a/.devcontainer/Dockerfile b/.devcontainer/Dockerfile
@@ -0,0 +1,11 @@
+# Devcontainer for meta-panda Yocto/kas builds.
+# Unlike the other PandABlocks repos (which use ubuntu-devcontainer), this is
+# based on the kas image, matching KAS_IMAGE_VERSION in build.sh.
+FROM ghcr.io/siemens/kas/kas:4.8 AS developer
+
+USER root
+
+# Add any system dependencies for the developer environment here
+# RUN apt-get update -y && apt-get install -y --no-install-recommends \
+#     some-tool \
+#     && apt-get clean
diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json
@@ -0,0 +1,24 @@
+// For format details, see https://containers.dev/implementors/json_reference/
+{
+    "name": "meta-panda Developer Container",
+    "build": {
+        "dockerfile": "Dockerfile",
+        "target": "developer"
+    },
+    "customizations": {
+        "vscode": {
+            // Add the IDs of extensions you want installed when the container is created.
+            "extensions": [
+                "redhat.vscode-yaml"
+            ]
+        }
+    },
+    "runArgs": [
+        "--net=host",
+        // Make sure SELinux does not disable access to host filesystems like tmp
+        "--security-opt=label=disable"
+    ],
+    // Mount the parent as /workspaces so peer repos are visible alongside
+    // this one, and bitbake build output can live outside the repo
+    "workspaceMount": "source=${localWorkspaceFolder}/..,target=/workspaces,type=bind"
+}
diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md
@@ -0,0 +1,18 @@
+# Contributing
+
+Contributions and issues are most welcome! All issues and pull requests are handled
+through [GitHub](https://github.com/PandABlocks/meta-panda/issues). Please check for any
+existing issues before filing a new one.
+
+## Issue or Pull Request?
+
+Raise an issue if you want to report a bug or request a feature. Open a pull request if
+you already have a change ready to propose. If you are unsure, raise an issue first to
+discuss the change.
+
+## Documentation
+
+Documentation is built with [MyST](https://mystmd.org) and published to GitHub Pages.
+The docs follow the [Diátaxis](https://diataxis.fr) framework — tutorials, how-to
+guides, reference and explanations. See `how-to/contribute` for the documentation
+authoring conventions and the cross-repository link setup.
diff --git a/.github/pages/index.html b/.github/pages/index.html
@@ -1,9 +1,11 @@
 <!DOCTYPE html>
 <html>
-  <head>
-    <title>Redirecting to master branch</title>
+
+<head>
+    <title>Redirecting to main branch</title>
     <meta charset="utf-8">
-    <meta http-equiv="refresh" content="0; url=./rel-v2023.2/index.html">
-    <link rel="canonical" href="rel-v2023.2/index.html">
-  </head>
+    <meta http-equiv="refresh" content="0; url=./main/index.html">
+    <link rel="canonical" href="main/index.html">
+</head>
+
 </html>
diff --git a/.github/pages/make_switcher.py b/.github/pages/make_switcher.py
@@ -0,0 +1,96 @@
+"""Make switcher.json to allow docs to switch between different versions."""
+
+import json
+import logging
+from argparse import ArgumentParser
+from pathlib import Path
+from subprocess import CalledProcessError, check_output
+
+
+def report_output(stdout: bytes, label: str) -> list[str]:
+    """Print and return something received frm stdout."""
+    ret = stdout.decode().strip().split("\n")
+    print(f"{label}: {ret}")
+    return ret
+
+
+def get_branch_contents(ref: str) -> list[str]:
+    """Get the list of directories in a branch."""
+    stdout = check_output(["git", "ls-tree", "-d", "--name-only", ref])
+    return report_output(stdout, "Branch contents")
+
+
+def get_sorted_tags_list() -> list[str]:
+    """Get a list of sorted tags in descending order from the repository."""
+    stdout = check_output(["git", "tag", "-l", "--sort=-v:refname"])
+    return report_output(stdout, "Tags list")
+
+
+def get_versions(ref: str, add: str | None) -> list[str]:
+    """Generate the file containing the list of all GitHub Pages builds."""
+    # Get the directories (i.e. builds) from the GitHub Pages branch
+    try:
+        builds = set(get_branch_contents(ref))
+    except CalledProcessError:
+        builds = set()
+        logging.warning(f"Cannot get {ref} contents")
+
+    # Add and remove from the list of builds
+    if add:
+        builds.add(add)
+
+    # Get a sorted list of tags
+    tags = get_sorted_tags_list()
+
+    # Make the sorted versions list from main branches and tags
+    versions: list[str] = []
+    for version in ["master", "main"] + tags:
+        if version in builds:
+            versions.append(version)
+            builds.remove(version)
+
+    # Add in anything that is left to the bottom
+    versions += sorted(builds)
+    print(f"Sorted versions: {versions}")
+    return versions
+
+
+def write_json(path: Path, repository: str, versions: list[str]):
+    """Write the JSON switcher to path."""
+    org, repo_name = repository.split("/")
+    struct = [
+        {"version": version, "url": f"https://{org}.github.io/{repo_name}/{version}/"}
+        for version in versions
+    ]
+    text = json.dumps(struct, indent=2)
+    print(f"JSON switcher:\n{text}")
+    path.write_text(text, encoding="utf-8")
+
+
+def main(args=None):
+    """Parse args and write switcher."""
+    parser = ArgumentParser(
+        description="Make a versions.json file from gh-pages directories"
+    )
+    parser.add_argument(
+        "--add",
+        help="Add this directory to the list of existing directories",
+    )
+    parser.add_argument(
+        "repository",
+        help="The GitHub org and repository name: ORG/REPO",
+    )
+    parser.add_argument(
+        "output",
+        type=Path,
+        help="Path of write switcher.json to",
+    )
+    args = parser.parse_args(args)
+
+    # Write the versions file
+    versions = get_versions("origin/gh-pages", args.add)
+    write_json(args.output, args.repository, versions)
+
+
+if __name__ == "__main__":
+    main()
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
@@ -2,47 +2,84 @@ name: Docs CI
 
 on:
   push:
+    branches:
+      - main
+      - docs
+    tags:
+      - '*'
   pull_request:
 
+permissions:
+  contents: write
+
 jobs:
-  make_docs:
+  build:
     runs-on: ubuntu-latest
-    container:
-      # TODO: use panda sdk image when available
-      image: ghcr.io/pandablocks/pandablocks-dev-container:latest
-      credentials:
-        username: ${{ github.actor }}
-        password: ${{ secrets.GITHUB_TOKEN }}
-      volumes:
-        - ${{ github.workspace }}:/repos
-        - ${{ github.workspace }}/build:/build
 
     steps:
-      # Git repositories
-      - name: Checkout Source
-        uses: actions/checkout@v2
+      - name: Avoid git conflicts when tag and branch pushed at same time
+        if: github.ref_type == 'tag'
+        run: sleep 60
+
+      - name: Checkout
+        uses: actions/checkout@v5
         with:
-          path: meta-panda
-          # require history to get back to last tag for version number of branches
+          # Need this to get version number from last tag
           fetch-depth: 0
 
-      # Build docs
-      - name: Make docs
+      # meta-panda is a Yocto layer, not a Python/uv project, so we install
+      # mystmd directly with npm rather than via `uv run tox -e docs`. The build
+      # command itself (`cd docs && myst build --html --strict`) matches the
+      # template. --strict makes the build exit non-zero on any error-severity
+      # message (e.g. an unresolved cross-repo xref), failing CI rather than
+      # publishing broken links.
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+
+      - name: Install MyST
+        run: npm install -g mystmd@1.10.1
+
+      - name: Sanitize ref name for docs version
+        run: echo "DOCS_VERSION=${GITHUB_REF_NAME//[^A-Za-z0-9._-]/_}" >> $GITHUB_ENV
+
+      # BASE_URL is required so assets/links resolve under the versioned Pages
+      # sub-path (https://pandablocks.github.io/meta-panda/$DOCS_VERSION/). This
+      # is the one deviation from the template, whose mystmd migration does not
+      # yet set it.
+      - name: Build docs
+        env:
+          BASE_URL: /meta-panda/${{ env.DOCS_VERSION }}
         run: |
-          cd meta-panda
-          python3 -m sphinx -M html docs /build/
+          cd docs
+          myst build --html --strict
+
+      # Drop the ~135 MB templates/ dir (downloaded book-theme node sources, a
+      # build-time cache) before uploading. We keep docs/_build as the artifact
+      # root so the archive retains the intermediate html/ directory; this trims
+      # the zip ~7x (51 MB -> ~7 MB) without changing its layout.
+      - name: Remove build cache from artifact
+        run: rm -rf docs/_build/templates
+
+      - name: Upload built docs artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: docs
+          path: docs/_build
 
       - name: Move to versioned directory
-        # e.g. master or 0.1.2
-        run: mv /build/html "meta-panda/.github/pages/${GITHUB_REF##*/}"
+        run: mv docs/_build/html .github/pages/$DOCS_VERSION
+
+      - name: Write switcher.json
+        run: python3 .github/pages/make_switcher.py --add $DOCS_VERSION ${{ github.repository }} .github/pages/switcher.json
 
       - name: Publish Docs to gh-pages
-        # Only master and tags are published
-        if: "${{ github.repository_owner == 'PandABlocks' && (startsWith(github.ref, 'refs/heads/rel-') || startsWith(github.ref, 'refs/tags')) }}"
+        if: github.ref_type == 'tag' || github.ref_name == 'main' || github.ref_name == 'docs'
         # We pin to the SHA, not the tag, for security reasons.
-        # https://docs.github.com/en/free-pro-team@latest/actions/learn-github-actions/security-hardening-for-github-actions#using-third-party-actions
-        uses: peaceiris/actions-gh-pages@bbdfb200618d235585ad98e965f4aafc39b4c501  # v3.7.3
+        # https://docs.github.com/en/actions/learn-github-actions/security-hardening-for-github-actions#using-third-party-actions
+        uses: peaceiris/actions-gh-pages@4f9cc6602d3f66b9c108549d475ec49e8ef4d45e # v4.0.0
         with:
           github_token: ${{ secrets.GITHUB_TOKEN }}
-          publish_dir: meta-panda/.github/pages
+          publish_dir: .github/pages
           keep_files: true
diff --git a/.gitignore b/.gitignore
@@ -1,2 +1,5 @@
 build/
 sources/
+
+# MyST build output
+docs/_build/
diff --git a/README.md b/README.md
@@ -0,0 +1,34 @@
+# meta-panda
+
+PandA is a programmable logic box for synchronised triggering and position
+capture in scientific experiments. You configure it by wiring together
+functional blocks in its FPGA — from a web browser or over a simple TCP
+protocol — and capture timestamped position data from it at high speed.
+
+This site is the root of the PandABlocks documentation: it covers getting a
+PandA on the network, using the Web Control, capturing data, administering and
+upgrading a PandA, and building its firmware and software. Documentation for
+the individual components (FPGA framework, TCP server, Python client, EPICS /
+Tango integration) is linked throughout.
+
+This repository itself is the `meta-panda` layer: the Yocto recipes and
+configuration for building the Linux system that runs on a PandA.
+
+- Machines provided: `pandabox`, `pandabox2`, `pandabrick`
+- Distro provided: `panda-petalinux`
+- Image provided: `panda-image`
+
+The Linux system brings up the network from a `config.txt` file on the SD card, runs an
+SSH server for debugging access, programs the FPGA and runs services such as the TCP
+server and Web Control, and serves a Web Admin interface on port 80 for installing and
+removing packages and adding SSH keys.
+
+<!-- README only content. Anything below this line will be excluded from the index page -->
+
+## Where to find things
+
+| | |
+|---|---|
+| Source code | <https://github.com/PandABlocks/meta-panda> |
+| Documentation | <https://PandABlocks.github.io/meta-panda> |
+| Releases | <https://github.com/PandABlocks/meta-panda/releases> |