Skip to content

Align and pin native Python declaration rows - #198

Merged
tony merged 5 commits into
mainfrom
p0-6-7-native-python
Oct 26, 2026
Merged

tony merged 5 commits into
mainfrom
p0-6-7-native-python

Conversation

@tony

@tony tony commented Oct 25, 2026 •

Copy link
Copy Markdown
Contributor

Native Python API pages, the Sphinx reference served through the docs shell at /en/py/<version>/api/, now align declaration controls with the signature's first line (P0 7) and pin the class declaration while you read its members (P0 6). Astro reference pages already had both.

  • Alignment (P0 7). On libtmux.Server, a wrapped signature centred its permalink, kind badge and source link on the whole signature, 11–24 px below the first line. They now sit on that line, within 0.2 px on the five measured declarations. The row and code region align to the start, the controls to the first baseline, and badges centre on that line. This applies only inside the shell, on the desktop layout.
  • Sticky class row (P0 6). Native pages have no member or group headings; members are nested dl.py.method blocks under one h1. As chosen by the maintainer:
    • The top-level class's own declaration row pins under the site header while you scroll its members, and releases at the class's end.
    • Methods, nested classes and functions stay in flow.
    • At 48em and below, the page's .content scrolls on its own, so the row stays in flow there.
  • Anchors stay visible. NativeSphinxScript.astro measures each pinned row and writes --native-class-row-height. Members' scroll-margin-top uses it, so a jump to a member lands about 8 px below the row, including the taller stacked row at 900 px. Without it, the member was covered by 22 px.
  • No JavaScript, no pinning. The pinned row, its fill and the member margin all require data-native-class-rows, which the script sets after its first measurement. Without it the page behaves as before.
  • :target highlight kept. Furo's dt:target rule is !important, and the fill also excludes :target.

What changed, and why: native Python was the one reference renderer without these two P0 behaviours. The changes are in site/src/styles/native-sphinx.css and site/src/components/docs/NativeSphinxScript.astro. Two small captured fixtures from the live stylesheets (layout.css, Furo's :target rule), each with its source URL and fetch date, let the tests run against the real native cascade.

Checks run:

  • Measurements: before and after were taken on the live HTML at 1440, 900, 769, 700 and 390 px, with the CSS and script injected for the after. They cover the five Server declarations, QueryList, and release on libtmux.common and libtmux.constants.
  • Tests: site/test/native-signature-layout.test.ts has 55 tests. Site vitest passes 197 files and 6,311 tests.
  • Break checks: each new assertion was shown to fail when its rule or code is removed. That covers the alignment override, the sticky rule, the marker gate, the width threshold, the gap's tie to scroll-padding-top, the fill excluding :target, the missing-dt guard and the missing-ResizeObserver guard.
  • Review: an independent reviewer read each of the four commits. It found the anchor overlap, the no-JS case and a test gap against the real stylesheet, all fixed here.
  • Not covered: C++ Breathe rows are not matched by these selectors. No built page was measured, only the live HTML with the changes injected.

Tool use: Claude Code planned the work. A Sonnet sub-agent measured and wrote the code and tests, independent Sonnet reviewers checked each commit, and Claude Code opened this pull request. The maintainer reviews it before merge.

tony added 5 commits October 25, 2026 12:51
…signature line

why: Native Python declarations centred the permalink, source link and
badges on the whole signature block. A signature wrapped over several
lines put them at its middle, 11 px below the first line for two lines
and 22 px for three, where the shared reference pages keep them level
with line one.

what:
- Align the native desktop declaration row and its code region to the
  start, and the controls to the baseline, with badges centred on that
  line
- Test the computed alignments inside the native shell, with the
  vendored rows outside it as the control
…mbers scroll

why: A native Python class page runs for tens of thousands of pixels, and
nothing on screen named the class once its own row scrolled away. The
alignment test also loaded the repo's vendored stylesheet, which has no
rule for the desktop declaration row, so it never showed the shell rules
beat the sheet native pages actually receive.

what:
- Pin the top-level class declaration under the site header on screens
  wider than 35rem, with an opaque surface and a scroll margin that
  lands anchored members below it; the row releases when its class ends
  and nested classes, methods and functions stay in flow
- Test the alignment and pinning against a fetched copy of the published
  layout stylesheet, with controls outside the shell, on a narrow screen
  and on method rows, and with each rule removed to prove the tests fail
- Record the stylesheet's source URL and fetch date beside the fixture
…pinned row

why: The scroll margin for anchored members was a fixed 1.5rem, but the
pinned class row varies in height. On a narrow column the row is 65.8 px
instead of 39.4 px, and an anchored member then landed 22 px under it.
The row also flattened the highlight of a targeted class, and below 48em
the sheet turns the article column into a scroll container, where the
row cannot pin at all.

what:
- Measure each top-level class row in NativeSphinxScript, on load and
  through a ResizeObserver, and write its height on the class; members
  take their scroll margin from that height
- Fill the pinned row only while it is not the target, so the target
  highlight stays
- Pin the row only from 48em up, where the column is not a scroll
  container
- Test the margin variable, the opaque fill, the z-index under the site
  header's 40, the kept highlight and the measuring script, each with a
  removal that fails
…asures them

why: The pinned row and its member scroll margin are CSS, but the margin
depends on a height that only NativeSphinxScript writes. With scripts
off, or after the script threw, the height was unset and every anchored
member landed under its class row. The highlight test also relied on an
invented :target rule instead of the one the native pages receive.

what:
- Set data-native-class-rows on the document after the first
  measurement, and gate the pinned row, its fill and the member scroll
  margin on it, so rows stay in flow without the script
- Capture the Furo sheet's own important dt:target rule as a fixture
  with its source and fetch date, and test that the fill never applies
  to a target
- Test the missing marker, pinning between 48em and 1024px, the 0.5rem
  gap tied to the shell's scroll padding, a class with no declaration
  row and a missing ResizeObserver, each with a removal that fails
why: astro check failed CI on #198: the new tests read and write the
row height through closest('dl').style, and happy-dom types closest()
as a plain Element without a style property.

what:
- Cast the dl to HTMLElement in the two helpers
- Drop the dt fixture's unused extra parameter
@tony
tony merged commit b676f57 into main Oct 26, 2026
3 checks passed
tony added a commit that referenced this pull request Oct 26, 2026
)

why: A Sphinx project could not link into libtmux.org, Rust types listed
their fields as plain members, native Python declaration rows drifted
out of line, and metadata pages such as the AI policy showed the tmux
sidebar. These five reviewed changes ship together so one CI run gates
them and one deploy wave publishes them.

what:
- #166: objects.inv per port and version and objects-full.inv across
  the advertised defaults, with portable labels; footer links to the
  scoped and full inventories with a help page; /meta/ pages on linking
  and Intersphinx with RST and MyST examples; the footer names a port's
  inventory only on pages inside that port's version tree
- #197: Rust structs and variants list their fields in a Name, Type,
  Description table, in HTML and the Markdown export
- #198: native Python declaration controls align with the first
  signature line, and top-level class declarations stay pinned
- #199: /meta/ pages get their own sidebar; /tmux/ pages keep the tmux
  tree without the meta pages
- #195: the README links the AI policy

Each PR is merged on this branch with its own "Title (#N)" merge
commit; #202 was held out for the next train.
@tony
tony temporarily deployed to docs-preview-cleanup October 26, 2026 06:42 — with GitHub Actions Inactive
tony added a commit to tmux-python/libtmux that referenced this pull request Oct 28, 2026
why: The site still presented libtmux as an alpha: badges, notices,
install commands and examples carried alpha pins and prerelease flags,
and a docs channel stood for a release state that no libtmux release
has. A Sphinx project had no inventory to link to, tmux commands and
cross-port links sat in small rows under each declaration, TypeScript
aliases showed no declaration, and native Python documentation pages
listed every page in one flat sidebar column.

what:
- Publish `objects.inv` and `targets.json` at the root of each port
  version, naming the pages, headings, workspace table rows, MCP schema
  fields, command options and API declarations the build rendered, and
  stop the build when an API declaration has no rendered target
  (`inventory.ts`, `inventory-publisher.ts`, `inventory-targets.ts`,
  `targets.ts`; libtmux/docs#166)
- Link the footer of a port page to the inventory of its port version,
  to the full inventory and to a guide on linking from Sphinx, and list
  the same inventory and target files in the `docs.json` manifest
  (`SiteFooter.astro`, `inventory-links.ts`, `docs.json.ts`;
  libtmux/docs#166)
- Export the rows of the shared workspace command and configuration
  tables as Sphinx option, setting and environment variable targets, and
  keep a page's identity across a move through `inventoryId` and
  `inventoryAliases` in its frontmatter (`rehype-row-anchors.ts`,
  `load.md`, `panes.md`, `environment.md`, `content.config.ts`;
  libtmux/docs#166)
- Link the AI policy, which the root site publishes at
  `/meta/ai-policy/`, from the footer (`SiteFooter.astro`,
  `ai-policy.md`; libtmux/docs#194)
- Show a final release on its badge as its series, 0.x for 0.1.0, with
  the line "Released; the API may change.", and replace the alpha notice
  with an early-release notice that returns once for a reader who
  dismissed it (`ports.ts`, `registry.json`, `PrereleaseNotice.astro`;
  libtmux/docs#200)
- Remove the stable docs channel: a release tag publishes at its own
  version, a prerelease also as `next`, and the newest final release tag
  is the default and indexed version, or `latest` while the port has
  none; an older tag pushed later does not take the default
  (`port-docs-identity.sh`, `publish-plan.mjs`, `gen-versions.mjs`,
  `versions.ts`; libtmux/docs#201)
- Leave a release-numbering label such as 0.1.N plain in prose instead
  of resolving it as an API name (`resolver.ts`; libtmux/docs#204)
- Give a symbol's tmux commands, tmux C declarations, hooks, options and
  formats, Guides and equivalents in other ports their own sections on
  its API reference page and in its Markdown export, ahead of Related
  types (`api-tmux-sections.ts`, `ApiTmuxSections.astro`,
  `ApiReference.astro`; libtmux/docs#202)
- Draw the nested guide line in every sidebar layout, set Grouped's
  group headings bold as Outline's are, and make the API glossary the
  last row of the reference sidebar and the last search result
  (`api-tree.css`, `ApiTree.astro`, `api-tree.ts`; libtmux/docs#208)
- Open the preview card of a glossary link only after the pointer rests
  on it for a second, and let Escape cancel a card that has not opened
  (`link-preview-browser.ts`; libtmux/docs#211)
- Let Tab move from the footer's inventory help link to the link in its
  tooltip at once (`SiteFooter.astro`; libtmux/docs#211)
- Set the title of an index-style reference page, such as API reference,
  in the sans face (`ApiReference.astro`; libtmux/docs#211)
- Start the permalink, source link and badges of a native Python
  declaration on its first signature line, so they stay level with it
  when the signature wraps (`native-sphinx.css`; libtmux/docs#198)
- Pin a top-level Python class declaration under the header while its
  members scroll, and offset an anchored member by the pinned row's
  measured height, none until it is measured, so it lands below the row
  (`native-sphinx.css`, `NativeSphinxScript.astro`; libtmux/docs#198,
  libtmux/docs#211)
- Show the Sphinx toctree in the sidebar of native Python documentation
  pages, with its captions as headings, branches that nest and open down
  to the current page, external rows that open in a new tab, and search
  results labelled by path (`native-shell-context.mjs`,
  `native-shell.ts`, `NativeShell.astro`; libtmux/docs#209)
- Set the section titles of the MCP reference in the sans face, and keep
  its sidebar guide line under the parent label and not through the
  row's own text (`ProtocolReference.astro`, `api-tree.css`;
  libtmux/docs#211)

Shared source: libtmux/docs
From: 00045828e6457d142d58933f603665a2ead35811
To:   e1ab401f7d6fca5ac9c418bc6c77ca382320cd2e
tony added a commit to tmux-python/libtmux that referenced this pull request Nov 7, 2026
why: The site still presented libtmux as an alpha: badges, notices,
install commands and examples carried alpha pins and prerelease flags,
and a docs channel stood for a release state that no libtmux release
has. A Sphinx project had no inventory to link to, tmux commands and
cross-port links sat in small rows under each declaration, TypeScript
aliases showed no declaration, and native Python documentation pages
listed every page in one flat sidebar column.

what:
- Publish `objects.inv` and `targets.json` at the root of each port
  version, naming the pages, headings, workspace table rows, MCP schema
  fields, command options and API declarations the build rendered, and
  stop the build when an API declaration has no rendered target
  (`inventory.ts`, `inventory-publisher.ts`, `inventory-targets.ts`,
  `targets.ts`; libtmux/docs#166)
- Link the footer of a port page to the inventory of its port version,
  to the full inventory and to a guide on linking from Sphinx, and list
  the same inventory and target files in the `docs.json` manifest
  (`SiteFooter.astro`, `inventory-links.ts`, `docs.json.ts`;
  libtmux/docs#166)
- Export the rows of the shared workspace command and configuration
  tables as Sphinx option, setting and environment variable targets, and
  keep a page's identity across a move through `inventoryId` and
  `inventoryAliases` in its frontmatter (`rehype-row-anchors.ts`,
  `load.md`, `panes.md`, `environment.md`, `content.config.ts`;
  libtmux/docs#166)
- Link the AI policy, which the root site publishes at
  `/meta/ai-policy/`, from the footer (`SiteFooter.astro`,
  `ai-policy.md`; libtmux/docs#194)
- Show a final release on its badge as its series, 0.x for 0.1.0, with
  the line "Released; the API may change.", and replace the alpha notice
  with an early-release notice that returns once for a reader who
  dismissed it (`ports.ts`, `registry.json`, `PrereleaseNotice.astro`;
  libtmux/docs#200)
- Remove the stable docs channel: a release tag publishes at its own
  version, a prerelease also as `next`, and the newest final release tag
  is the default and indexed version, or `latest` while the port has
  none; an older tag pushed later does not take the default
  (`port-docs-identity.sh`, `publish-plan.mjs`, `gen-versions.mjs`,
  `versions.ts`; libtmux/docs#201)
- Leave a release-numbering label such as 0.1.N plain in prose instead
  of resolving it as an API name (`resolver.ts`; libtmux/docs#204)
- Give a symbol's tmux commands, tmux C declarations, hooks, options and
  formats, Guides and equivalents in other ports their own sections on
  its API reference page and in its Markdown export, ahead of Related
  types (`api-tmux-sections.ts`, `ApiTmuxSections.astro`,
  `ApiReference.astro`; libtmux/docs#202)
- Draw the nested guide line in every sidebar layout, set Grouped's
  group headings bold as Outline's are, and make the API glossary the
  last row of the reference sidebar and the last search result
  (`api-tree.css`, `ApiTree.astro`, `api-tree.ts`; libtmux/docs#208)
- Open the preview card of a glossary link only after the pointer rests
  on it for a second, and let Escape cancel a card that has not opened
  (`link-preview-browser.ts`; libtmux/docs#211)
- Let Tab move from the footer's inventory help link to the link in its
  tooltip at once (`SiteFooter.astro`; libtmux/docs#211)
- Set the title of an index-style reference page, such as API reference,
  in the sans face (`ApiReference.astro`; libtmux/docs#211)
- Start the permalink, source link and badges of a native Python
  declaration on its first signature line, so they stay level with it
  when the signature wraps (`native-sphinx.css`; libtmux/docs#198)
- Pin a top-level Python class declaration under the header while its
  members scroll, and offset an anchored member by the pinned row's
  measured height, none until it is measured, so it lands below the row
  (`native-sphinx.css`, `NativeSphinxScript.astro`; libtmux/docs#198,
  libtmux/docs#211)
- Show the Sphinx toctree in the sidebar of native Python documentation
  pages, with its captions as headings, branches that nest and open down
  to the current page, external rows that open in a new tab, and search
  results labelled by path (`native-shell-context.mjs`,
  `native-shell.ts`, `NativeShell.astro`; libtmux/docs#209)
- Set the section titles of the MCP reference in the sans face, and keep
  its sidebar guide line under the parent label and not through the
  row's own text (`ProtocolReference.astro`, `api-tree.css`;
  libtmux/docs#211)

Shared source: libtmux/docs
From: 00045828e6457d142d58933f603665a2ead35811
To:   e1ab401f7d6fca5ac9c418bc6c77ca382320cd2e

This branch was previously deployed

2 inactive deployments
docs-preview-cleanup — 419ad787 Deployed Oct 26, 2026 by tony via cleanup #176
docs-preview — 419ad787 Deployed Oct 25, 2026 by tony via publish-preview / publish #992
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.

1 participant