Skip to content

ci: build the docs, strictly, and fix what that surfaced - #279

Merged
robcohen merged 1 commit into
mainfrom
chore/docs-ci
Aug 9, 2026
Merged

ci: build the docs, strictly, and fix what that surfaced#279
robcohen merged 1 commit into
mainfrom
chore/docs-ci

Conversation

@robcohen

@robcohen robcohen commented Aug 9, 2026

Copy link
Copy Markdown
Member

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

Found while verifying #278 (a pymdown-extensions 10 → 11 major), where the
absence 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 cannot
resolve them as pages. Relinked to their canonical GitHub URLs, which is what
development.md already does for LICENSE.

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 description
above it.

--strict is what makes it a gate

Measured, on a reintroduced dead link:

exit
with --strict 1
without --strict 0, warning printed

A build that reports a broken page and exits 0 is exactly 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 can't drift — the job is just docs,
the same way the mypy job is just mypy.

Verification

sabotage result
reintroduce a dead link just docs exits 1
un-indent the Raises continuation just docs exits 1
restored tree exit 0, 0 warnings

Also re-verified after mdformat reflowed the edited prose — the strict build is
still clean at 0 warnings, and the links survived rewrapping.

The docstring edit is comment-only; query_shell tests pass (7).

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.
@robcohen
robcohen merged commit 782d53e into main Aug 9, 2026
33 checks passed
@robcohen
robcohen deleted the chore/docs-ci branch August 9, 2026 18:13
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant