Skip to content

docs: diagrams, release gate on the docs site; release 3.0.2 - #22

Merged
Akinzou merged 2 commits into
masterfrom
docs/diagrams
Nov 11, 2026
Merged

Akinzou merged 2 commits into
masterfrom
docs/diagrams

Conversation

@Akinzou

@Akinzou Akinzou commented Nov 11, 2026 •

Copy link
Copy Markdown
Owner

What

  • Diagrams (Mermaid): retries and magic-number scope in the README and user guide; layers, ports, the open_position request flow and concurrency on the architecture page. See ADR 0014.
  • Pinned Mermaid with SRI: overrides/main.html loads Mermaid 11.17.2 with a sha384 integrity hash (cross-checked against jsDelivr's hash of the npm file). Material uses it instead of fetching the newest 11.x.
  • CI renders every diagram (scripts/check_diagrams.py, headless Chrome with sandbox) with the same file and hash, in its own docs.yml job. The deploy waits for it. It also fails on a Mermaid fence written in a form it cannot extract, and when Mermaid never loaded.
  • PyPI: at publish, scripts/replace_readme_diagrams.py swaps each diagram for a link to its README section on GitHub. The pin step then pins it to the tag, so a release links its own diagrams. It refuses a diagram that would swallow other text.
  • Release gate: python-publish.yml refuses to publish until the docs.yml deploy job succeeded for the tagged commit, so the site linked from PyPI already shows the release.
  • Release 3.0.2: documentation only. Since v3.0.1 the src/ changes are docstrings only, checked by comparing each module's AST with docstrings removed.

Verification

  • Local: ruff, ruff format, mypy, pytest (413 passed, 9 skipped), check_file_length.py, mkdocs build --strict, check_diagrams.py (6 diagrams render).
  • Publish dry run for refs/tags/v3.0.2: diagrams replaced (2), links pinned (34, including #retries and #magic-numbers-whose-trades-a-call-touches), twine check --strict passes.
  • On purpose: a ; in a sequence label, a ~~~ fence and a wrong integrity hash each fail check_diagrams.py.
  • The built site loads only mermaid@11.17.2 (checked from the browser's resource list).

Review

/code-review high, four rounds, about 40 findings. Fixed: every finding that would ship something wrong to readers, PyPI or the release, including:

  • two diagrams that contradicted the code;
  • a lazy match that could delete README text on PyPI;
  • a docs gate that passed with the deploy skipped;
  • a schedule that could cancel a deploy.

Not fixed, with the reason:

  • check_diagrams.py may hang on Windows when Edge outlives a timeout. This only affects local runs; CI uses Chrome on Linux.
  • Each document is scanned twice, once per wrapper function. That costs milliseconds and keeps the wrappers testable.

Static analysis

Semgrep: 0 findings at ERROR and 0 at WARNING (97 + 98 rules).

…aits for the site

Diagrams: retries and magic-number scope in the README (and so the user
guide); layers, ports, the request flow and concurrency in the architecture
page (ADR 0014).

- overrides/main.html pins Mermaid 11.17.2 with a Subresource Integrity hash;
  Material uses it instead of fetching the newest 11.x.
- scripts/check_diagrams.py renders every diagram in headless Chrome with that
  file and hash, in its own docs.yml job; the deploy waits for it. It also
  fails on a Mermaid fence written in a form it cannot extract.
- scripts/replace_readme_diagrams.py swaps each diagram, at publish, for a link
  to its README section on GitHub, before the links are pinned to the tag. It
  refuses a diagram that would swallow other text.
- scripts/mermaid_fences.py is the one definition both scripts use.
- python-publish.yml refuses a release until the docs.yml deploy job succeeded
  for the tagged commit, so the site PyPI links already shows the release.
- Tests import scripts/ through pytest's pythonpath instead of four copies of
  an importlib loader.

Chose a pinned URL with an integrity hash over a vendored copy because it pins
the file without 3 MB in the repository. Chose one shared fence definition over
a copy per script because two copies would let CI pass a README the publish
then refuses.
Documentation only: the library code is unchanged since 3.0.1 apart from docstrings (checked by comparing each module's AST without them).
@Akinzou
Akinzou merged commit c7cf9ac into master Nov 11, 2026
11 checks passed
@Akinzou
Akinzou deleted the docs/diagrams branch November 14, 2026 01:24
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