docs: S23.12 generate relationship diagrams on API pages#619
Conversation
Render a post-it "realised by" class diagram at the top of each vtable role's API page, generated from code at docs-build time. - relationship_data.py: extract the role -> implementers graph from the headers (every implementer is a public factory returning struct SolidSyslog<Role>*); derive each backend's package and the Null object. Runs standalone to dump the graph. - relationship_render.py: render a self-contained inline SVG in the post-it kit style — interface top-centre, a generalisation tree with the hand-drawn hollow realises triangle, backends beneath (one row for <=4, two staggered rows for >=5), font scaled to fit the longest name, Null grey, a small override for the decorator backends that wrap their own role (Stream's TLS pair). - relationship_diagrams.py: MkDocs on_page_markdown hook that injects the diagram onto each role's base page (dispatch header, else the vtable Definition). Every sticky links to its API page. - postit-defs.svg: the kit's realises marker is now a hand-drawn hollow triangle (closed, slightly bowed) rather than an open chevron. - mkdocs.yml: register the hook. Covers all 13 vtable roles, generated from code — no per-role hand-authoring. Closes #618
☀️ Quality Summary 🚦 build-linux-gcc: 100% successful (✔️ 1522 passed) Created by Quality Monitor v1.14.0 (#f3859fd). More details are shown in the GitHub Checks Result. |
|
@coderabbitai review |
✅ Action performedReview finished.
|
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Path: .coderabbit.yaml Review profile: ASSERTIVE Plan: Pro Plus Run ID: 📒 Files selected for processing (2)
WalkthroughChangesThe change adds build-time extraction of vtable role relationships, inline SVG rendering for interface and backend links, and a MkDocs hook that prepends diagrams to matching API pages. Relationship diagrams
Estimated code review effort: 4 (Complex) | ~45 minutes Sequence Diagram(s)sequenceDiagram
participant MkDocs
participant relationship_diagrams
participant relationship_data
participant relationship_render
participant APIPage
MkDocs->>relationship_diagrams: process page Markdown
relationship_diagrams->>relationship_data: build_graph(repository root)
relationship_data-->>relationship_diagrams: return role relationship graph
relationship_diagrams->>relationship_render: render_svg(role, info)
relationship_render-->>relationship_diagrams: return inline SVG
relationship_diagrams->>APIPage: prepend diagram for matching API page
relationship_diagrams-->>MkDocs: return updated Markdown
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@hooks/relationship_render.py`:
- Line 14: Replace the hard-coded BASE_URL used by the relationship SVG link
generation with MkDocs’ configured site URL or a page-relative URL helper,
ensuring links remain valid under mkdocs serve and alternate deployment
prefixes. Update the URL construction in the relationship rendering logic that
uses BASE_URL, including the node links near the referenced locations.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Pro Plus
Run ID: 9bb41e6f-fe47-4a01-a320-a140cfe474d0
⛔ Files ignored due to path filters (1)
docs/assets/postit/postit-defs.svgis excluded by!**/*.svg,!**/*.svg,!docs/assets/**
📒 Files selected for processing (4)
hooks/relationship_data.pyhooks/relationship_diagrams.pyhooks/relationship_render.pymkdocs.yml
CodeRabbit: BASE_URL hard-coded the /solid-syslog/ prefix, so the diagram's node links would break under `mkdocs serve` or any other deployment prefix. Diagrams are always injected on an api/<name>_8h/ page, so a sibling API page is one level up — use "../<page>/". Verified the built Stream page now emits href="../SolidSyslogPosixTcpStream_8h/" and strict build stays green.
☀️ Quality Summary 🚦 build-linux-gcc: 100% successful (✔️ 1522 passed) Created by Quality Monitor v1.14.0 (#f3859fd). More details are shown in the GitHub Checks Result. |
1 participant
Renders a post-it "realised by" class diagram at the top of every vtable role's API page, generated from code at docs-build time and injected via a MkDocs hook. Addresses the "show relationships" item from the doc-site first-impression backlog.
How it works
hooks/relationship_data.py) — the role → implementers graph comes straight from the headers: every implementer is a public factory returningstruct SolidSyslog<Role>*. Package and the Null object are derived from the file path / name. Runs standalone (python hooks/relationship_data.py) to dump the graph.hooks/relationship_render.py) — a self-contained inline SVG in the post-it kit's hand-drawn style. Simple, followable rules for the general case:MbedTlsHmacSha256Policy, 23 chars);hooks/relationship_diagrams.py) — anon_page_markdownhook prepends the diagram onto each role's base page (the consumer dispatch header where there is one, else the vtableDefinition— e.g.SecurityPolicy). Styles are id-scoped so nothing leaks into the page; every sticky links to its own API page.Covers all 13 vtable roles (2–7 backends each) with no per-role hand-authoring. The kit's
realisesmarker (postit-defs.svg) is upgraded from an open chevron to the hand-drawn hollow triangle.Verified
mkdocs build --strictpasses. Rendered and reviewed all 13 roles on the local server — big/small, one-/two-row, the no-Null role (Address), and theDefinition-page fallback (SecurityPolicy).Follow-up (not in scope)
The already-committed post-it diagrams (
architecture,storage,sl1/2/3) still inline the old chevron marker and want re-inlining now the kit uses the triangle.Closes #618
🤖 Generated with Claude Code
Summary by CodeRabbit