FazBrowse GitHub Viewer | Trending |
URL:
| Home
Tools: [Download Repo ZIP]   [Original HTTPS Page]

docs(events,mutations,platform_metrics): add API reference pages by Adebowale-Morakinyo · Pull Request #31 · pythonnative/pythonnative · GitHub

Repository navigation

docs(events,mutations,platform_metrics): add API reference pages - #31

Merged
owenthcarey merged 2 commits into
pythonnative:mainfrom
Adebowale-Morakinyo:docs/api-events-mutations-metrics
Sep 1, 2026
Merged

owenthcarey merged 2 commits into
pythonnative:mainfrom
Adebowale-Morakinyo:docs/api-events-mutations-metrics

Conversation

Copy link
Copy Markdown
Contributor

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)

  • Three new pages following docs/api/reconciler.md: title, one-paragraph summary, the
    mkdocstrings block with identical options and filters, then Next steps.
  • The ::: blocks for mutations and events are removed from native_views.md, leaving a
    one-line pointer under each existing heading, per @owenthcarey's direction on the issue.
  • Nav entries sit directly after Native views rather than appended, keeping them adjacent to
    the page that points at them and inside the internals cluster.
  • Per the second ask, all four pages cross-link: each new page's Next steps names the other two
    plus Native views, and Native views names all three.
  • IOS_TAB_BAR_BASE_HEIGHT_PT is a documented public constant that mkdocstrings silently
    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

  • site/ deleted and rebuilt from clean, mkdocs build --strict exit 0.
  • ./scripts/check.sh passes end to end.
  • Each page verified against its module's AST to render exactly the expected symbols with no typing leakage, and the HTML grepped for duplicate anchors: 34 symbols, each with exactly one, and zero left on native_views.
  • Cross-reference audit (Owen's ask): all 25 references were traced through the generated HTML one by one. None needed editing — every reference names a symbol rather than a page, so autorefs re-pointed all 21 that render, and the remaining 4 live in the deliberately unrendered platform handler modules. One reference improved for free: platform_metrics.py:153 pointed at set_safe_area_insets, which previously resolved to nothing.

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:

  • Rows in docs/api/pythonnative.md's "Where to look next" table for all three pages. The
    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.
  • The native_views.md intro now links "mutation ops" to the new page, since that prose
    promised content that has moved.

IOS_TAB_BAR_BASE_HEIGHT_PT was documented with Sphinx-style #: comments,
which griffe doesn't parse, so mkdocstrings dropped the constant from the
rendered output entirely. Converting to the PEP 258 form used everywhere
else in the package makes it render. This was the only file in
src/pythonnative/ using #:. The value and type are unchanged.
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
owenthcarey merged commit a9b5147 into pythonnative:main Sep 1, 2026
15 checks passed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters. Learn more about bidirectional Unicode characters
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.

Add API reference pages for events, mutations, and platform_metrics

2 participants


Back | FazBrowse Home | New Git URL