Code clean-up and documentation refresh

docs/dev/adrs/suggestions/documentation-ci-build.md → docs/dev/adrs/accepted/documentation-ci-build.md

@@ -1,6 +1,6 @@
 # ADR: Documentation CI and Build Verification
 
-**Status:** Proposed  
+**Status:** Accepted  
 **Date:** 2026-05-31
 
 ## Group
@@ -77,6 +77,20 @@ Use `codespell` first for low-noise spelling checks. Consider `Vale`
 after the project has a small EasyDiffraction style vocabulary and an
 allowlist for crystallographic terms, package names, and CIF tags.
 
+## Implementation Status
+
+Most of this ADR is already in place; it is accepted to record the
+chosen direction and to track the remaining gaps.
+
+| #   | Decision                     | Status                                                                                                                                                                                       |
+| --- | ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 1   | MkDocs `--strict` build      | **Done** — `docs-build` pixi task runs `mkdocs build --strict`; wired into the `lint-format.yml` "docs strict build" gate and the `docs.yml` deploy workflow.                                |
+| 2   | `mkdocstrings` for API pages | **Done** — `mkdocstrings` + `mkdocstrings-python` configured in `docs/mkdocs.yml` (handler `paths: ['src']`); the `api-reference/*.md` pages use `:::` directives.                           |
+| 3   | Snippet smoke tests          | **Not done** — no task imports or executes the user-facing snippets in `quick-reference/`, `user-guide/first-steps.md`, or `user-guide/analysis-workflow/*.md`. Highest-value remaining gap. |
+| 4   | Tutorial freshness check     | **Partial** — `notebook-prepare` plus `notebook-tests`/`notebook-exec-ci` exist, but no no-write task asserts that `notebook-prepare` leaves the committed `.ipynb` unchanged.               |
+| 5   | `lychee` link checking       | **Done for local/relative links** — `link-check` pixi task (config in `lychee.toml`) is wired into `lint-format.yml`. External-URL checking is deferred (see issue 114).                     |
+| 6   | `codespell`, then `Vale`     | **codespell done** — `spell-check` pixi task wired into `lint-format.yml`. `Vale` deferred.                                                                                                  |
+
 ## Options Considered
 
 ### MkDocs strict build
@@ -179,11 +193,14 @@ Cons:
 
 ## Deferred Work
 
-- Decide whether link checking runs on every pull request, nightly, or
-  both.
-- Decide whether snippet smoke tests extract fenced code blocks
+- Add snippet smoke tests for user-facing examples (decision 3). Tracked
+  by the `documentation-snippet-tests` implementation plan. Open
+  question carried into that plan: extract fenced code blocks
   automatically or rely on explicitly named snippets.
-- Decide whether docs CI should build only source Markdown or also build
-  rendered notebooks.
-- Add the chosen checks to `pixi.toml`, CI configuration, and developer
-  documentation after this ADR is accepted.
+- Add a no-write `notebook-prepare-check` task that fails CI when the
+  committed notebooks are out of date with their `.py` sources (decision
+  4).
+- Enable external-URL link checking in the docs gate (decision 5),
+  scheduled or cached to avoid flakiness. Tracked by issue 114.
+- Adopt `Vale` prose linting once an EasyDiffraction style vocabulary
+  and crystallographic-term allowlist exist (decision 6).

docs/dev/adrs/accepted/plotting-docs-performance.md

@@ -450,7 +450,7 @@ Settled in discussion on 2026-06-02:
   payload + faster draw) — a separate, data-side optimization.
 - A docs CI budget check (page weight / figure count) to catch
   regressions, aligning with
-  [`documentation-ci-build.md`](../suggestions/documentation-ci-build.md).
+  [`documentation-ci-build.md`](documentation-ci-build.md).
 - Hoist a single importmap into the **report** template `<head>` for
   standalone reports that render multiple Three.js scenes (the same
   per-scene-importmap bug as docs, but governed by

docs/dev/adrs/accepted/test-suite-and-validation.md

@@ -66,7 +66,7 @@ accumulated:
   slow and therefore runs on pull requests only. There is no fast,
   every-push check that the site builds strictly, links resolve, and
   prose is clean. This overlaps the unimplemented
-  [Documentation CI and Build Verification](../suggestions/documentation-ci-build.md)
+  [Documentation CI and Build Verification](documentation-ci-build.md)
   suggestion.
 
 This ADR amends [Test Strategy](../accepted/test-strategy.md): the
@@ -338,7 +338,7 @@ prompt drift feedback. It is deliberately **separate from `docs.yml`**,
 which executes all tutorials and then builds and deploys — slow, and
 therefore pull-request-only. The detailed catalogue of documentation
 checks is owned by
-[Documentation CI and Build Verification](../suggestions/documentation-ci-build.md),
+[Documentation CI and Build Verification](documentation-ci-build.md),
 which this ADR coordinates with: that ADR defines _what_ the checks are;
 this ADR's decision is that the cheap, deterministic subset runs as part
 of the every-push test workflow. Promoting that ADR is part of this
@@ -443,15 +443,15 @@ drafting conversation, per the dependency-approval rule):
 - `pytest-benchmark` — performance-regression benchmarks (§7).
 
 Coordinated with
-[Documentation CI and Build Verification](../suggestions/documentation-ci-build.md),
+[Documentation CI and Build Verification](documentation-ci-build.md),
 which carries the documentation-check tools (`codespell`, a link checker
 such as `lychee`, and later `Vale`) used by §9.
 
 ## Related ADRs
 
 - [Test Strategy](../accepted/test-strategy.md) — amended by this ADR.
-- [Documentation CI and Build Verification](../suggestions/documentation-ci-build.md)
-  — coordinated with §9.
+- [Documentation CI and Build Verification](documentation-ci-build.md) —
+  coordinated with §9.
 - [Lint Complexity Thresholds](../accepted/lint-complexity-thresholds.md)
   — sibling Quality guardrail.
 - [Notebook Generation Source of Truth](../accepted/notebook-generation.md)

docs/dev/adrs/index.md

@@ -33,7 +33,7 @@ folders.
 | Documentation        | Accepted   | Help Method Discoverability                         | Requires primary public objects and facades to expose consistent `help()` output.                                          | [`help-discoverability.md`](accepted/help-discoverability.md)                               |
 | Documentation        | Accepted   | Notebook Generation Source of Truth                 | Treats tutorial `.py` files as editable sources and notebooks as generated artifacts.                                      | [`notebook-generation.md`](accepted/notebook-generation.md)                                 |
 | Documentation        | Accepted   | Plotting & Docs Performance for Interactive Figures | Self-hosts a lazy, shared figure runtime so docs pages load fast and progressively while staying interactive.              | [`plotting-docs-performance.md`](accepted/plotting-docs-performance.md)                     |
-| Documentation        | Suggestion | Documentation CI and Build Verification             | Proposes strict MkDocs builds, API-derived docs, snippet smoke tests, link checks, and prose/spelling checks.              | [`documentation-ci-build.md`](suggestions/documentation-ci-build.md)                        |
+| Documentation        | Accepted   | Documentation CI and Build Verification             | Strict MkDocs builds, API-derived docs, snippet smoke tests, link checks, and prose/spelling checks.                       | [`documentation-ci-build.md`](accepted/documentation-ci-build.md)                           |
 | Experiment model     | Accepted   | Immutable Experiment Type                           | Makes experiment type axes creation-time state rather than mutable runtime state.                                          | [`immutable-experiment-type.md`](accepted/immutable-experiment-type.md)                     |
 | Experiment model     | Accepted   | Automatic Line-Segment Background Estimation        | Detects line-segment background control points from the measured pattern, peak-insensitive and editable.                   | [`background-auto-estimate.md`](accepted/background-auto-estimate.md)                       |
 | Experiment model     | Accepted   | Calculation Without Measured Data                   | Adds a writable `data_range` category so a structure-only experiment is calculable and plottable without loaded data.      | [`calculation-without-measured-data.md`](accepted/calculation-without-measured-data.md)     |