You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/dev/adrs/accepted/documentation-ci-build.md
+10-10Lines changed: 10 additions & 10 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -82,14 +82,14 @@ allowlist for crystallographic terms, package names, and CIF tags.
82
82
Most of this ADR is already in place; it is accepted to record the
83
83
chosen direction and to track the remaining gaps.
84
84
85
-
| # | Decision | Status |
86
-
| - | -------- | ------ |
87
-
| 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. |
88
-
| 2 |`mkdocstrings` for API pages |**Done** — `mkdocstrings` + `mkdocstrings-python` configured in `docs/mkdocs.yml` (handler `paths: ['src']`); the `api-reference/*.md` pages use `:::` directives. |
89
-
| 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. |
90
-
| 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. |
91
-
| 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). |
92
-
| 6 |`codespell`, then `Vale`|**codespell done** — `spell-check` pixi task wired into `lint-format.yml`. `Vale` deferred. |
| 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.|
88
+
| 2 |`mkdocstrings` for API pages |**Done** — `mkdocstrings` + `mkdocstrings-python` configured in `docs/mkdocs.yml` (handler `paths: ['src']`); the `api-reference/*.md` pages use `:::` directives.|
89
+
| 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. |
90
+
| 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.|
91
+
| 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).|
92
+
| 6 |`codespell`, then `Vale`|**codespell done** — `spell-check` pixi task wired into `lint-format.yml`. `Vale` deferred.|
93
93
94
94
## Options Considered
95
95
@@ -198,8 +198,8 @@ Cons:
198
198
question carried into that plan: extract fenced code blocks
199
199
automatically or rely on explicitly named snippets.
200
200
- Add a no-write `notebook-prepare-check` task that fails CI when the
201
-
committed notebooks are out of date with their `.py` sources
202
-
(decision 4).
201
+
committed notebooks are out of date with their `.py` sources (decision
202
+
4).
203
203
- Enable external-URL link checking in the docs gate (decision 5),
204
204
scheduled or cached to avoid flakiness. Tracked by issue 114.
205
205
- Adopt `Vale` prose linting once an EasyDiffraction style vocabulary
0 commit comments