Repository navigation
Align and pin native Python declaration rows - #198
Merged
Merged
Conversation
…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
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
temporarily deployed
to
docs-preview-cleanup
October 26, 2026 06:42 — with
GitHub Actions
Inactive
This was referenced Oct 27, 2026
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
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
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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.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.dl.py.methodblocks under oneh1. As chosen by the maintainer:.contentscrolls on its own, so the row stays in flow there.NativeSphinxScript.astromeasures each pinned row and writes--native-class-row-height. Members'scroll-margin-topuses 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.data-native-class-rows, which the script sets after its first measurement. Without it the page behaves as before.:targethighlight kept. Furo'sdt:targetrule 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.cssandsite/src/components/docs/NativeSphinxScript.astro. Two small captured fixtures from the live stylesheets (layout.css, Furo's:targetrule), each with its source URL and fetch date, let the tests run against the real native cascade.Checks run:
QueryList, and release onlibtmux.commonandlibtmux.constants.site/test/native-signature-layout.test.tshas 55 tests. Site vitest passes 197 files and 6,311 tests.scroll-padding-top, the fill excluding:target, the missing-dtguard and the missing-ResizeObserverguard.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.