ci(docs): publish docs/ to GitHub Pages with MkDocs Material

.github/workflows/docs.yml

@@ -0,0 +1,72 @@
+name: docs
+
+# Builds the MkDocs site from docs/ and publishes it to GitHub Pages.
+#
+# The build job runs on every PR that touches docs so a broken link fails
+# review rather than the deploy. Only pushes to main deploy.
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "docs/**"
+      - "mkdocs.yml"
+      - ".github/workflows/docs.yml"
+  pull_request:
+    paths:
+      - "docs/**"
+      - "mkdocs.yml"
+      - ".github/workflows/docs.yml"
+  # Allows a manual redeploy without pushing a docs change.
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+# Serialize deploys. Do not cancel in progress: a half-finished Pages deploy
+# leaves the live site in whatever state it got to.
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: "3.12"
+
+      # Deliberately not `pip install -e ".[docs]"`. That extra exists for local
+      # previews, but installing the package here would drag in PyQt5, pydm and
+      # pyepics to render markdown. The two names are kept in sync by hand; if
+      # they drift, this job still builds the same site.
+      - name: Install MkDocs
+        run: pip install mkdocs mkdocs-material
+
+      # --strict turns a broken internal link into a failed build. The docs
+      # cross-reference each other with relative .md paths, so this is the
+      # check that actually matters.
+      - name: Build
+        run: mkdocs build --strict
+
+      - uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0
+        with:
+          path: site
+
+  deploy:
+    # PRs build but do not publish.
+    if: github.event_name != 'pull_request'
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@cd2ce8fcbc39b97be8ca5fce6e763baed58fa128 # v5.0.0

MANIFEST.in

@@ -14,6 +14,7 @@ exclude .flake8
 exclude requirements.txt
 exclude *.sh
 exclude Makefile
+exclude mkdocs.yml
 recursive-exclude tests *
 recursive-exclude .github *
 global-exclude __pycache__

README.md

@@ -7,7 +7,7 @@ Operator displays, analysis tools, and command-line interface for the LCLS-II su
 
 The LCLS superconducting linac accelerates an electron beam through five sections (L0B–L4B) containing 60 cryomodules and 480 superconducting RF cavities. This package provides the software used by operators and physicists to control, monitor, and commission those cavities: PyDM-based GUIs, hierarchical setup automation, fault monitoring, and analysis tools for Q0 measurement, microphonics, and tuning.
 
-For architecture documentation and per-application guides, see [`docs/`](docs/index.md).
+For architecture documentation and per-application guides, see the [documentation site](https://slaclab.github.io/sc_linac_physics/) or browse [`docs/`](docs/index.md) in the repo.
 
 ## Installation
 

docs/getting_started.md

@@ -5,7 +5,7 @@ By the end you will have written three working displays from scratch, each build
 
 ## Prerequisites
 
-Follow the installation steps in [README.md](../README.md)
+Follow the installation steps in [README.md](https://github.com/slaclab/sc_linac_physics/blob/main/README.md)
 
 ## Background
 

mkdocs.yml

@@ -0,0 +1,62 @@
+site_name: SC Linac Physics
+site_description: Controls, displays, and analysis tools for the SLAC SC Linac
+site_url: https://slaclab.github.io/sc_linac_physics/
+repo_url: https://github.com/slaclab/sc_linac_physics
+repo_name: slaclab/sc_linac_physics
+edit_uri: edit/main/docs/
+
+docs_dir: docs
+
+# Fail the build on a broken internal link or a nav entry that does not resolve.
+# The docs cross-reference each other heavily with relative .md paths, so a
+# silent 404 is the most likely way this site rots.
+strict: true
+
+theme:
+  name: material
+  features:
+    - navigation.sections
+    - navigation.top
+    - content.code.copy
+    - search.highlight
+  palette:
+    - media: "(prefers-color-scheme: light)"
+      scheme: default
+      toggle:
+        icon: material/weather-night
+        name: Switch to dark mode
+    - media: "(prefers-color-scheme: dark)"
+      scheme: slate
+      toggle:
+        icon: material/weather-sunny
+        name: Switch to light mode
+
+plugins:
+  - search
+
+markdown_extensions:
+  - admonition
+  - attr_list
+  - tables
+  - toc:
+      permalink: true
+  - pymdownx.superfences
+  - pymdownx.details
+
+nav:
+  - Home: index.md
+  - Getting Started: getting_started.md
+  - Infrastructure:
+      - Linac Hardware Model: utils/linac_model.md
+      - Shared Utilities: utils/shared_utilities.md
+  - Applications:
+      - Auto Setup: applications/auto_setup.md
+      - RF Commissioning: applications/rf_commissioning.md
+      - Q0 Measurement: applications/q0.md
+      - Microphonics: applications/microphonics.md
+      - Quench Processing: applications/quench_processing.md
+      - Tuning: applications/tuning.md
+  - Displays:
+      - Cavity Display: displays/cavity_display.md
+      - Fault Heatmap: displays/fault_heatmap.md
+      - SRF Home: displays/srf_home.md

pyproject.toml

@@ -46,6 +46,10 @@ dev = [
     "twine",
     "check-manifest",
 ]
+# For previewing the docs site locally: `mkdocs serve`. CI installs these two
+# directly rather than through this extra, to avoid pulling the whole runtime
+# in just to render markdown -- see .github/workflows/docs.yml.
+docs = ["mkdocs", "mkdocs-material"]
 
 [tool.black]
 line-length = 80
@@ -232,6 +236,7 @@ ignore = [
     "requirements.txt",
     "*.sh",
     "Makefile",
+    "mkdocs.yml",
     ".git*",
     ".pre-commit-config.yaml",
     # Test data (in git but not in distribution)