Adds dedicated pages for the three modules, following the structure of
docs/api/reconciler.md, with nav entries and rows in the package index.
events and mutations were already rendered as sections of
docs/api/native_views.md, so adding pages without removing those blocks
would give every symbol two anchors. Constructed in a scratch copy, that
aborts the strict build with 49 autorefs warnings across the 13 public
names in events alone. Those two blocks are now one-line pointers to the
new pages, per the maintainer's direction on the issue.
All 25 existing cross-references name symbols rather than pages, so they
re-point automatically; each was traced through the generated HTML to
confirm. platform_metrics.py:153 previously resolved to nothing and now
has a target.
Closes pythonnative#24
What
Three new API reference pages — docs/api/events.md, docs/api/mutations.md, docs/api/platform_metrics.md — plus nav entries, index rows, and the removal of two now-duplicate render blocks from docs/api/native_views.md.
Closes #24.
Why
The issue describes all three modules as having "no page at all." That's true only for platform_metrics. events and mutations were already fully rendered as sections of native_views.md (:32 and :23). Adding new pages without removing those blocks isn't a cosmetic duplication — it breaks CI: constructed in a scratch copy, it produces Aborted with 49 warnings in strict mode!, one mkdocs_autorefs: Multiple primary URLs found per symbol across all 13 public names in events, because two anchors leave autorefs unable to resolve any of the 21 site-wide references to them.
So the pure-addition task in the issue is really a small restructuring, which is what @owenthcarey confirmed.
How (brief)
mkdocstrings block with identical options and filters, then Next steps.
one-line pointer under each existing heading, per @owenthcarey's direction on the issue.
the page that points at them and inside the internals cluster.
plus Native views, and Native views names all three.
dropped, because platform_metrics.py was the only file in src/pythonnative/ documenting an
attribute with Sphinx-style #: comments, which griffe doesn't parse as a docstring.
Converting four comment lines to a PEP 258 docstring, matching events.py:27, is a runtime
no-op — value and type verified unchanged — and makes the constant render. The alternative,
show_if_no_docstring: true on the page, would have surfaced every other undocumented
attribute as a side effect.
Testing
Risks/Impact
Anchors for the events and mutations symbols move from api/native_views/ to the new pages.
Every in-repo reference re-points automatically, but an external bookmark or link to something
like api/native_views/#pythonnative.events.dispatch_event will still reach a valid page and
no longer reach that anchor. Unavoidable given the move, and the reason for keeping the two
pointer lines where the sections used to be.
Docs/Follow-ups
Two disclosed additions beyond the acceptance criteria, both deliberate:
criteria don't mention it, but every other API page has a row, and a page absent from the
index is a page readers won't find.
promised content that has moved.