docs: S23.22 drop the Doxygen kind from generated API headings - #747
Conversation
mkdoxy titles every member with its kind, so pages read "function SolidSyslogFile_Close", "define SOLIDSYSLOG_FILE_POOL_SIZE", "variable Acquire", and each table of contents repeated the word once per member. The section above already names the kind, so the prefix only pushed the name to the right: 311 headings across functions, macros, enums, typedefs and struct members. The heading text is what MkDocs turns into the anchor, so dropping a word would move every anchor and break the links pointing at it — mkdoxy links its own pages that way, two hand-written pages use #function- anchors, and so does the product page on the company website. Nothing validates an inbound link, so that breakage would not have surfaced. Each heading therefore states its old anchor explicitly, generated by calling the same slugify the site configures for toc rather than reconstructed by rule. Verified against the published site: all 957 anchors on the 230 generated pages still exist after the change. Anonymous enums keep their kind, since a heading reading "@0" says less than "enum @0". Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Anchor validation was held at info because the mkdoxy-generated pages were said to emit anchors like #enum-@0 that could not resolve. Nothing in the built site links to an @-style anchor any more, and a strict build reports no unresolved anchor, so the exemption bought nothing. It cost something, though: renaming the generated member headings broke 17 mkdoxy cross-page links, and the build stayed green while reporting them at info. A link into a heading that has moved is what this validation is for. Proved it fails: a link to a nonexistent anchor aborts the strict build. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
WalkthroughThe PR adds a MkDocs hook that removes supported Doxygen member-kind prefixes from generated API headings. It preserves original anchors, excludes anonymous enums, limits changes to ChangesAPI heading normalisation
Estimated code review effort: 3 (Moderate) | ~20 minutes Sequence Diagram(s)sequenceDiagram
participant MkDocs
participant on_page_markdown
participant GeneratedApiPage
participant AnchorValidation
MkDocs->>on_page_markdown: generated markdown for an api/ page
on_page_markdown->>GeneratedApiPage: match and retitle supported headings
GeneratedApiPage-->>MkDocs: headings with preserved anchors
MkDocs->>AnchorValidation: rendered links and anchors
AnchorValidation-->>MkDocs: warnings for missing anchors
Possibly related PRs
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✨ Finishing Touches 💡 1📝 Generate docstrings 💡
🧪 Generate unit tests (beta)
Comment |
☀️ Quality Summary Created by Quality Monitor v4.15.0 (#82d77af). More details are shown in the GitHub Checks Result. |
![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/test_api_member_headings.py`:
- Around line 69-73: Update test_a_cross_page_link_to_a_member_still_resolves to
render the target structSolidSyslogConfig.md content containing the Clock member
heading, then assert the rendered output includes the explicit `#variable-clock`
anchor rather than only checking the source link text in out.
🪄 Autofix
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
Run ID: 46f7cdbf-0b23-449e-830a-26f709dad018
📒 Files selected for processing (3)
hooks/api_member_headings.pyhooks/test_api_member_headings.pymkdocs.yml
1 participant
Purpose
Part of #708.
Every heading on a generated API page carried its Doxygen kind —
function SolidSyslogFile_Close,define SOLIDSYSLOG_FILE_POOL_SIZE,variable Acquire— and each page's table of contents repeated the word once per member. The
section above the heading already names the kind, so the prefix only pushed the
name to the right in the one place a reader scans.
Change Description
A build hook,
hooks/api_member_headings.py, drops the kind from the 311member headings across functions, macros, enums, typedefs and struct members.
The heading text is what MkDocs turns into the anchor, so dropping a word moves
every anchor on the page and breaks the links pointing at it. Those links exist
in three places: mkdoxy links its own header and directory pages at the members
they declare,
hardening-path.mdandapi-reference/index.mdcarry eight#function-links, and the product page on the company website links#function-solidsyslog_logand#function-solidsyslog_service. Nothingvalidates a link pointing into the site, so that breakage would not surface.
Each heading therefore states its old anchor explicitly, via
attr_list. Theanchor is not reconstructed by rule — it is produced by calling the same
slugify the site configures for
toc, so it matches whatever that would havegenerated, including cases no rule of mine would have got right.
Anonymous enums keep their kind. Doxygen names them
@0…@5, and a headingreading
@0says less thanenum @0.The second commit makes anchor validation fatal under
--strict. It was heldat
infofor anchors like#enum-@0that mkdoxy was said to emit; nothing inthe built site links to an
@-style anchor any more, and the strict buildreports no unresolved anchor, so the exemption bought nothing. It cost
something: the first version of this change broke 17 mkdoxy cross-page links
and the build stayed green while reporting them at
info.Test Evidence
Nine new tests in
hooks/test_api_member_headings.py, driven red first — theopening test failed on a missing module, and the generalisation to
functionfailed on the un-rewritten heading before the kinds were folded together.
They cover each kind mkdoxy emits, the anchor each heading keeps, the
anonymous-enum exception, hand-written pages being untouched, and a cross-page
link still resolving.
mkdocs-mkdoxyimagemkdocs build --strictexits 0scripts/check_platform_docs.pyexits 0The anchors are verified by comparison rather than by argument. Every anchor on
the published site was captured first — 957 across 230 generated pages — then
the site was rebuilt and the two compared: no anchor was lost, including
the two the product page links to.
The new gate is proved to fail: a link to a nonexistent anchor aborts the
strict build with exit 1, naming the file, the link and the missing anchor.
Areas Affected
hooks/andmkdocs.yml. Documentation build only — no library source, nopublic headers, no CI workflow changes. The generated
api/tree isgit-ignored, so the effect is visible only in a built site.
Anchor validation becoming fatal applies to every page, not just generated
ones: a hand-written link to a heading that later moves now fails the build
rather than logging at
info.Summary by CodeRabbit
New Features
Bug Fixes