ci: build the docs, strictly, and fix what that surfaced - #279
Merged
Conversation
Nothing built the documentation. `pymdown-extensions` and the rest of
the `docs` group could be bumped and the site could break with every
check green — which is how four problems accumulated unnoticed:
docs/usage.md dead link to ../contrib/docker/README.md
docs/deployment.md dead link to ../contrib/docker/README.md
docs/deployment.md dead link to ../SECURITY.md
query_shell.py:229 griffe could not parse the Raises block
Both link targets exist in the repo; they are just outside `docs/`, so
mkdocs cannot resolve them as pages. Relinked to their canonical GitHub
URLs, which is what `development.md` already does for `LICENSE`.
The griffe one is a continuation line that was not indented, so
`query failed.` read as a new entry rather than the rest of the
description above it.
`--strict` is the part that makes this a gate. Measured, on a
reintroduced dead link:
with --strict exit 1
without --strict exit 0, warning printed
A build that reports a broken page and exits 0 is why these survived.
The flag goes in the `just docs` recipe rather than only in the
workflow, so a developer and CI run the same command and cannot drift —
the job is `just docs`, exactly as the mypy job is `just mypy`.
Sabotage-verified: a dead link fails it, an un-indented Raises
continuation fails it, and the restored tree builds clean at 0 warnings.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Nothing built the documentation.
pymdown-extensionsand the rest of thedocsgroup could be bumped, and the site could break, with every check green — which
is how four problems accumulated unnoticed:
docs/usage.md../contrib/docker/README.mddocs/deployment.md../contrib/docker/README.mddocs/deployment.md../SECURITY.mdquery_shell.py:229RaisesblockFound while verifying #278 (a
pymdown-extensions10 → 11 major), where theabsence of a docs build meant the green checks said nothing about it.
The fixes
Both link targets exist — they are just outside
docs/, so mkdocs cannotresolve them as pages. Relinked to their canonical GitHub URLs, which is what
development.mdalready does forLICENSE.The griffe warning was a continuation line that wasn't indented, so
query failed.read as a new entry rather than the rest of the descriptionabove it.
--strictis what makes it a gateMeasured, on a reintroduced dead link:
--strict--strictA build that reports a broken page and exits 0 is exactly why these survived. The
flag goes in the
just docsrecipe rather than only in the workflow, so adeveloper and CI run the same command and can't drift — the job is
just docs,the same way the mypy job is
just mypy.Verification
just docsexits 1Raisescontinuationjust docsexits 1Also re-verified after
mdformatreflowed the edited prose — the strict build isstill clean at 0 warnings, and the links survived rewrapping.
The docstring edit is comment-only;
query_shelltests pass (7).