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

[lisazacarias]

What this changes

Builds docs/ into a documentation site with MkDocs Material and deploys it to GitHub Pages on push to main. Today the docs are only readable as files in the repo.

Independent of #288 — see Scope.

Operator-visible

None. Documentation tooling only — no PV writes, no application behavior changes, no launch changes. mkdocs.yml is excluded from both the sdist and the wheel, so nothing operators install changes.

Scope

One commit, 6 files, +142/−2. No src/ changes, no test changes.

Deliberately contains no reference to the auto-tune explainer in #288, so the two can land in either order. The coupling was only two lines — an Explainers nav entry and a docs/index.md row — and both were removed here. MkDocs copies non-markdown files from docs_dir into the site regardless of nav, so when #288 lands its relative index link resolves on the site with no change needed to mkdocs.yml. Verified by building both ways: strict passes with the explainer absent, and with it present-but-not-in-nav (still copied byte-identical).

Decisions worth recording

MkDocs rather than Jekyll-from-/docs. Every internal doc link is a relative .md path (applications/tuning.md, utils/linac_model.md#pv-naming-conventions), and README.md links into docs/index.md three times. MkDocs rewrites .md links to built URLs, so they keep working both on the site and in GitHub's blob view. Plain Jekyll would 404 on every one unless each were rewritten to .html, which breaks GitHub browsing. A bare artifact upload would serve .md as plain text. MkDocs is the only option costing zero changes to existing content.

strict: true is deliberate. These docs cross-reference each other heavily, so a silent 404 is exactly how the site rots. It paid for itself immediately: it caught docs/getting_started.md linking ../README.md, which is outside docs_dir and therefore unresolvable. That is now an absolute GitHub URL, which works both on the site and on github.com — the one content change in this PR.

CI installs mkdocs/mkdocs-material directly rather than through the new docs extra. pip install -e ".[docs]" would drag in PyQt5, pydm and pyepics to render markdown. The extra exists for local previews (mkdocs serve); the workflow keeps the two names in sync by hand. Noted in a comment in docs.yml.

Actions pinned to full SHAs, per the org policy documented in .github/dependabot.yml. Dependabot will bump them.

Testing

• mkdocs build --strict — exits 0, no warnings
• check-manifest — passes, confirming the new mkdocs.yml ignore entry keeps package / verify green
• pytest — 3137 passed, 3 skipped, unchanged
• black (400 files) / flake8 (0) clean

Verified by serving the built output locally: / renders, every table link resolves, .md links become directory URLs, and the anchor utils/linac_model/#pv-naming-conventions is preserved.

Before this takes effect

Pages must be switched to build from Actions — a repo setting, not part of the PR:

gh api -X POST repos/slaclab/sc_linac_physics/pages -f build_type=workflow

The deploy job fails until that is done, and the new README.md site link 404s until the first deploy succeeds. Worth doing at merge time.

[github-actions]

🟢 PR size: 144 lines — within target

+142 / -2 in production code.
0 test and asset files excluded.

Largest files	Change
.github/workflows/docs.yml	+72/-0
mkdocs.yml	+62/-0
pyproject.toml	+5/-0
docs/getting_started.md	+1/-1
README.md	+1/-1

_{Target is 400 lines excluding tests, hard stop around 800 — see
"Scope and shipping" in CLAUDE.md. If this PR is over, the description
should say why it could not be split. Advisory only; this check never
fails the build.}

[Copilot]

Pull request overview

Adds MkDocs Material tooling and a GitHub Actions workflow to build the existing docs/ tree into a GitHub Pages site, keeping documentation readable both in-repo and as a rendered site.

Changes:

• Introduces mkdocs.yml (MkDocs Material config) with strict: true and an explicit navigation structure.
• Adds a docs optional dependency extra for local previews and a docs GitHub Actions workflow to build/deploy Pages from docs/.
• Updates doc entry points/links (README and docs/getting_started.md) to point to the deployed site and to avoid MkDocs strict link failures.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
README.md	Links to the new GitHub Pages documentation site while preserving in-repo browsing via docs/.
pyproject.toml	Adds a docs extra for local MkDocs previewing; excludes mkdocs.yml from check-manifest.
mkdocs.yml	Configures MkDocs Material theme, extensions, strict link checking, and site nav.
MANIFEST.in	Excludes mkdocs.yml from the sdist to keep packaging output unchanged.
docs/getting_started.md	Replaces an out-of-docs_dir relative link with a resolvable GitHub URL under strict builds.
.github/workflows/docs.yml	Builds MkDocs on PRs/pushes and deploys to GitHub Pages on main (pinned action SHAs).

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.