| M7-19/0 |
2026-10-14 |
The ticket was built on an integration base and ported onto main with only its own commits; the English docs of main win, and text this ticket adds is English. Rulings use the row form of this file (M7-19/<n> under a ticket heading) instead of the brief's D-M7-19-<n> in section 10, as the other ported tickets do. The two __init__ methods of the hook carry docstrings because main's ruff configuration requires them (rule D107). |
The tickets are built in parallel on integration bases; main takes each ticket as one pull request; merged names win (D-W-100). |
| M7-19/1 |
2026-10-14 |
Generator (Design note 1): an in-repository MkDocs hook, tools/docs/mkdocs_api_reference.py, renders both documents to static Markdown with the pinned pyyaml and mkdocs; no new dependency. Compared with the pinned Redocly CLI 2.62.1 build-docs (plus the AsyncAPI HTML template for the gateway). Evidence: redocly build-docs docs/api/openapi.yaml rendered the OpenAPI 3.1 document without errors, but its default page loads redoc.standalone.js from cdn.redocly.com and a Google Fonts stylesheet, is one 6.9 MB HTML file outside the site's navigation and search, and renders no AsyncAPI; the gateway would need @asyncapi/cli and its template as a further npm tree (not in tools/node, not tried). The hook renders the 304 operations, 35 webhook events, 560 schemas and 93 gateway messages offline, with no script, in the site's theme, search and strict link and anchor validation; Apache-2.0 as the repository; maintained here. This replaces the suggestion redocly build-docs of ADR 0045. |
Requirement 9 and 13 (no CDN, no external asset) and requirement 12 (both references in every build); the static hook meets them without bundling a JavaScript application. |
| M7-19/2 |
2026-10-14 |
Generated pages live only in the build: api/reference/rest.md, api/reference/schemas.md and api/reference/gateway.md are added as generated files in on_files and listed in the nav under API; nothing is committed. A committed file at one of these paths, a missing document, an unresolved local $ref or two equal anchors fail the build. Anchors are op-<operationid lower case>, schema-<Name>, response-<Name>, header-<Name>, security-<name>, channel-<key>, operation-<key> and message-<key> (characters other than letters, digits, _ and - become -). Text of the documents is used as Markdown with < escaped outside code spans; a code span wrapped over two lines is joined. docs/api/README.md names the site paths in code, not as links, because the pages do not exist for make linkcheck. |
Requirement 12: a stale generated file cannot be committed; the strict build validates every generated link and anchor. |
| M7-19/3 |
2026-10-14 |
External asset rule: tools/docs/external_assets_check.py site runs in make docs after the build and fails on a <script src>, a <link href> with rel stylesheet, preload, modulepreload or prefetch, or a CSS url(...) or @import (in <style>, style attributes and .css files) whose URL names a host. Anchors and links that load nothing (rel="canonical") pass, data: URLs pass, an empty site fails. Requests a bundled script makes at run time are out of its reach; the known one is Material's Mermaid loader (CDN, accepted in ADR 0045 "Consequences"), which the reference pages do not use. |
Requirement 13 in the form the brief gives (a check over the built HTML); the run-time loader is an existing, recorded decision and outside this ticket's scope. |
| M7-19/4 |
2026-10-14 |
Test first held: test_external_assets_check.py and test_mkdocs_api_reference.py were written and run red (module not found) before the check and the hook existed. |
Honest record of the order of work. |