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

.devcontainer/devcontainer.json

@@ -0,0 +1,55 @@
+// For format details, see https://containers.dev/implementors/json_reference/
+{
+    "name": "PandABlocks-server Developer Container",
+    "build": {
+        "dockerfile": "../Dockerfile",
+        "target": "developer"
+    },
+    "remoteEnv": {
+        // Allow X11 apps to run inside the container
+        "DISPLAY": "${localEnv:DISPLAY}",
+        // Put things that allow it in the persistent cache
+        "PRE_COMMIT_HOME": "/cache/pre-commit",
+        "UV_CACHE_DIR": "/cache/uv",
+        "UV_PYTHON_CACHE_DIR": "/cache/uv-python",
+    },
+    "customizations": {
+        "vscode": {
+            // Set *default* container specific settings.json values on container create.
+            "settings": {
+                // Workaround to prevent garbled python REPL in the terminal
+                // https://github.com/microsoft/vscode-python/issues/25505
+                "python.terminal.shellIntegration.enabled": false
+            },
+            // Add the IDs of extensions you want installed when the container is created.
+            "extensions": [
+                "ms-python.python",
+                "ms-azuretools.vscode-docker"
+            ]
+        }
+    },
+    // Create the config folder for the bash-config feature and uv cache
+    "initializeCommand": "mkdir -p ${localEnv:HOME}/.config/terminal-config",
+    "runArgs": [
+        // Allow the container to access the host X11 display and EPICS CA
+        "--net=host",
+        // Make sure SELinux does not disable with access to host filesystems like tmp
+        "--security-opt=label=disable"
+    ],
+    "mounts": [
+        // Mount in the user terminal config folder so it can be edited
+        {
+            "source": "${localEnv:HOME}/.config/terminal-config",
+            "target": "/user-terminal-config",
+            "type": "bind"
+        },
+        // Keep a persistent cross container cache for uv, pre-commit, and the venvs
+        {
+            "source": "devcontainer-shared-cache",
+            "target": "/cache",
+            "type": "volume"
+        }
+    ],
+    // Mount the parent as /workspaces so we can pip install peers as editable
+    "workspaceMount": "source=${localWorkspaceFolder}/..,target=/workspaces,type=bind",
+}

.github/CONTRIBUTING.md

@@ -0,0 +1,17 @@
+# Contributing
+
+Contributions and issues are most welcome! All issues and pull requests are handled
+through [GitHub](https://github.com/PandABlocks/PandABlocks-server/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.

.github/workflows/ci.yml

@@ -0,0 +1,67 @@
+name: Docs CI
+
+# Build + verify the docs on every event, then publish on INTERNAL events. The
+# build (the shared `docs.yml`) runs for PRs (including forks), pushes to main, and
+# tags, and uploads each build's `docs` artifact. Publishing is nested here (the
+# `publish` job -> the shared `publish.yml`) so its status is visible on the
+# PR/commit, but ONLY for internal events on this repo: a fork PR's build runs with a
+# read-only token and must never deploy.
+#
+# Both halves are consumed from DiamondLightSource/myst-version-switcher-plugin at a
+# pinned tag — this repo carries no docs-build/publish workflow of its own.
+# publish.yml reconstructs the whole versioned site from durable sources (main's
+# latest build persisted at _sources/main.zip, each release's docs.zip asset, every
+# open PR's build artifact) and deploys it to Pages directly; there is no gh-pages
+# branch.
+on:
+  pull_request:
+  push:
+    branches: [main]
+    tags: ['*']            # '*' never matches '/'
+
+jobs:
+  docs:
+    uses: DiamondLightSource/myst-version-switcher-plugin/.github/workflows/docs.yml@v0.7.0
+    with:
+      # `make docs` drives npx mystmd (pinned by MYSTMD_VERSION) and reads build
+      # settings from CONFIG, so create it first. eval runs the compound command.
+      build-command: cp CONFIG.example CONFIG && make docs
+      # The fork-PR warning links here so a maintainer can publish a fork preview.
+      preview-workflow: preview-fork.yml
+
+  # Tag-only: attach this build's docs.zip (bare html/ root) to the GitHub Release
+  # so `assemble` can reconstruct that released version on future deploys.
+  docs-release:
+    needs: [docs]
+    if: github.ref_type == 'tag'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: docs
+      - env:
+          GH_TOKEN: ${{ github.token }}
+        run: gh release upload "${{ github.ref_name }}" docs.zip --clobber --repo "${{ github.repository }}"
+
+  # Internal events only: an internal PR, or a push to main/tag, has a same-repo
+  # build we can trust + deploy. Fork PRs (head repo != this repo) are excluded —
+  # docs.yml's build job warns them instead. publish.yml defaults guard-default-branch
+  # to true, so every deploy asserts main is present and can never silently drop
+  # /main/ (main is self-durable via _sources/main.zip).
+  publish:
+    needs: [docs]
+    if: >-
+      github.repository == 'PandABlocks/PandABlocks-server' &&
+      ( github.event_name != 'pull_request' ||
+        github.event.pull_request.head.repo.full_name == github.repository )
+    uses: DiamondLightSource/myst-version-switcher-plugin/.github/workflows/publish.yml@v0.7.0
+    with:
+      version-name: ${{ needs.docs.outputs.version-name }}
+    permissions:
+      contents: read
+      actions: read
+      pages: write
+      id-token: write
+      statuses: write

.github/workflows/code.yml

@@ -42,7 +42,7 @@ jobs:
           cd PandABlocks-rootfs
           ln -s CONFIG.example CONFIG
           make kernel PLATFORM=${{matrix.platform}}
-
+      
       - name: Make zpkg
         run: |
           cd PandABlocks-server

.github/workflows/preview-fork.yml

@@ -0,0 +1,31 @@
+name: Preview fork PR
+
+# Maintainer opt-in to publish a versioned docs preview for an EXTERNAL fork PR.
+# Fork PRs build + verify in Docs CI but never auto-publish (their build runs with a
+# read-only token), so this is the only path that deploys one. A reusable workflow
+# can't be workflow_dispatch'd cross-repo, so this thin wrapper lives here and passes
+# the PR number through to the shared publish.yml via workflow_call.
+#
+# It approves the fork PR's CURRENT head SHA (a `preview-approved` commit status) and
+# assembles the site with that PR's artifact included. A later push to the PR (new
+# SHA) drops the preview until you re-run this. version-name is empty: there is no
+# in-run build to inject, so publish.yml does a pure durable gather.
+on:
+  workflow_dispatch:
+    inputs:
+      pr:
+        description: Fork PR number to approve + preview.
+        required: true
+
+jobs:
+  preview:
+    uses: DiamondLightSource/myst-version-switcher-plugin/.github/workflows/publish.yml@v0.7.0
+    with:
+      version-name: ""
+      pr: ${{ inputs.pr }}
+    permissions:
+      contents: read
+      actions: read
+      pages: write
+      id-token: write
+      statuses: write

.gitignore

@@ -4,3 +4,6 @@
 *.pyc
 tests/fpga_sequences
 /venv
+
+# MyST build output
+docs/_build/

CONFIG.example

@@ -15,9 +15,11 @@ BUILD_DIR = /build/build-server
 #
 PYTHON = python3
 
-# Sphinx build for documentation.
+# Version of mystmd (https://mystmd.org) used to build the documentation with
+# `make docs` / `make docs-dev`.  Run on demand via npx, so no global install is
+# needed.
 #
-SPHINX_BUILD = sphinx-build
+MYSTMD_VERSION = 1.10.1
 
 # Compiler settings.  Default cross compile prefix given here.  If BINUTILS_DIR
 # is specified it will be prepended to the path for building the driver and

Dockerfile

@@ -0,0 +1,10 @@
+# The devcontainer should use the developer target and run as root with podman
+# or docker with user namespaces.
+FROM ghcr.io/diamondlightsource/ubuntu-devcontainer:resolute AS developer
+
+# Add any system dependencies for the developer/build environment here.
+# Candidates: an ARMv7-A cross-compiler toolchain for on-PandA builds; the
+# native toolchain below is enough for the simulation server and docs.
+RUN apt-get update -y && apt-get install -y --no-install-recommends \
+    npm \
+    && apt-get dist-clean

Makefile

@@ -7,7 +7,7 @@ TOP := $(CURDIR)
 
 BUILD_DIR = $(TOP)/build
 PYTHON = python3
-SPHINX_BUILD = sphinx-build
+MYSTMD_VERSION = 1.10.1
 COMPILER_PREFIX = $(COMPILER_PREFIX_$(PLATFORM))
 KERNEL_DIR = $(error Define KERNEL_DIR in CONFIG file)
 PANDA_ROOTFS = $(error Define PANDA_ROOTFS in CONFIG file)
@@ -140,16 +140,33 @@ slow_load: $(SLOW_LOAD)
 
 # ------------------------------------------------------------------------------
 # Documentation
+#
+# Docs are built with MyST (mystmd), run through npx so no global install is
+# needed; pin the version with MYSTMD_VERSION (see CONFIG.example).  `make docs`
+# mirrors `myst build --html --strict` and `make docs-dev` mirrors `myst start`,
+# matching the docs/ task runner.  MyST writes its output into docs/_build/html.
+# --strict exits non-zero on any error-severity message (e.g. an unresolved
+# cross-repo xref) so CI fails rather than publishing broken links.
 
-$(DOCS_BUILD_DIR)/index.html: $(wildcard docs/*.rst docs/*/*.rst docs/conf.py)
-	$(SPHINX_BUILD) -b html docs $(DOCS_BUILD_DIR)
+MYST = npx --yes --package mystmd@$(MYSTMD_VERSION) myst
 
-docs: $(DOCS_BUILD_DIR)/index.html
+docs:
+	cd docs && $(MYST) build --html --strict
+
+docs-dev:
+	cd docs && $(MYST) start
 
 clean-docs:
-	rm -rf $(DOCS_BUILD_DIR)
+	rm -rf $(TOP)/docs/_build
 
-.PHONY: docs clean-docs
+.PHONY: docs docs-dev clean-docs
+
+# The zpkg packaging installs the built docs from $(DOCS_BUILD_DIR) (the `html`
+# entry in etc/panda-server.list), so stage the MyST output there for zpkg.
+$(DOCS_BUILD_DIR)/index.html: docs
+	rm -rf $(DOCS_BUILD_DIR)
+	mkdir -p $(DOCS_BUILD_DIR)
+	cp -r $(TOP)/docs/_build/html/. $(DOCS_BUILD_DIR)
 
 
 # ------------------------------------------------------------------------------

README.md

@@ -0,0 +1,24 @@
+# PandABlocks-server
+
+The PandA socket server provides a bridge between the register interface to the
+FPGA firmware controlling the PandA hardware and users and other software. The
+interface is designed to be simple and robust.
+
+The PandA firmware is structured into numerous functional blocks, each
+configured via a number of fields. This structure is directly reflected in the
+functional interface provided by this server: most commands read or write
+specific fields.
+
+The server publishes two socket end points: one for configuration control
+(simple ASCII commands, ASCII responses) and one for streamed data capture
+(no commands, a lightly structured binary stream).
+
+<!-- README only content. Anything below this line will be excluded from the index page -->
+
+## Where to find things
+
+| | |
+|---|---|
+| Source code | <https://github.com/PandABlocks/PandABlocks-server> |
+| Documentation | <https://PandABlocks.github.io/PandABlocks-server> |
+| Releases | <https://github.com/PandABlocks/PandABlocks-server/releases> |