Skip to content

Make API references searchable and easier to scan - #65

Merged
tony merged 8 commits into
mainfrom
feat-reference-reading-layout
Oct 2, 2026
Merged

tony merged 8 commits into
mainfrom
feat-reference-reading-layout

Conversation

@tony

@tony tony commented Oct 2, 2026 •

Copy link
Copy Markdown
Contributor

Reference readers need to find core objects and their members without navigating long package names and dense lists. Add scoped symbol search over the existing API inventory, concise headings with compact package or namespace rows and exact-name copying, and a responsive reading layout adapted from the supplied Java reference design.

Wide pages have a contents column and related APIs derived from ownership, inheritance and declared return types. Stable section links match the content each declaration renders, including parameters, returns, errors and examples. Member rows are grouped without changing their semantic order. Phone and tablet layouts retain the section links and existing navigation drawer. All surfaces use the site's light and dark theme colors. The mobile toolbar uses those colors before JavaScript initializes; without JavaScript, native disclosures provide navigation and contents links. Native overloads use the full card width, with metadata above them. Keywords, receiver and parameter bindings stay plain code at normal text contrast; only API references are linked. Scala collection names resolve before bare aliases in the JDK inventory, while explicit Java imports keep their Java targets.

Search accepts qualified names, owner/member queries and spaced names. It preserves each language's symbol kinds, distinguishes Scala variants, and prioritizes core objects and listings. Swift operators remain searchable without outranking listings for a bare owner query. Native Python search redirects retain the selected port, version, preview prefix and query.

Refresh Java and Kotlin Server documentation from the merged source comments in libtmux-java#47. The description explains sessions, windows, panes, socket selection and cleanup before transport details.

Validation

  • pnpm test passes in 45.38 seconds within the 60-second budget. Browser checks cover scoped queries, category filters, keyboard focus, inventory failure and retry, exact-name copying, clipboard refusal, section targets and active links, related declarations, semantic member order, and responsive layouts, full-width Scala overloads, declaration tokens without links, Scala Vector targets, and signature contrast without JavaScript in both themes. Phone checks also verify the toolbar surface before theme initialization, native disclosure keyboard use, and contents links without JavaScript.
  • Registry-driven search checks cover all 13 ports. Negative controls detect alphabetical ordering, lost queries, a Scala property preceding its Server type, and Swift operators preceding Server listings. Additional negative controls reject alphabetical member grouping, links on declaration bindings and JDK aliases overriding Scala collection types.
  • Source-link checks read original symbol IDs independently of declaration anchors. Negative controls detect missing known source links and preserve the documented exemption for inherited Swift declarations without source locations.
  • Manual browser review covers the assembled Kotlin and Scala pages at 1440 and 390 pixels in light and dark themes, including the compact package row, exact qualified-name copying and JavaScript-disabled rendering. A complete local assembly at the preceding signature-contrast revision generated 16,828 pages and checked 2,975,051 links with zero broken targets. The assembled API preview is refreshed. A subsequent complete assembly including the tmux CLI reference and this exact layout revision checked 17,103 pages and 3,151,363 links with zero broken targets. Hosted run 36982120158 passed the publication audit, preview artifact check and publication. The uploaded preview was verified at phone width: Scala declaration tokens have full-opacity dark foreground, Vector links to Scala, and JavaScript-disabled root navigation has a dark toolbar, 28 usable links and no horizontal overflow. An independent reviewer found no new blockers in the layout changes; the existing Java model identity and overload-field gaps remain assigned to separate fixes.
  • A negative control restoring the white toolbar fails the new browser assertion. Existing unresolved API mentions remain visible. Full reference resolution and the remaining examples overhaul are still open.

@tony
tony force-pushed the feat-reference-reading-layout branch from 1680921 to f9b0d0f Compare October 2, 2026 01:56
@tony
tony force-pushed the feat-reference-reading-layout branch from f9b0d0f to 2ded840 Compare October 2, 2026 02:16
@tony
tony deployed to docs-preview October 2, 2026 02:31 — with GitHub Actions Active
@tony
tony force-pushed the feat-reference-reading-layout branch from 2ded840 to 83b8c35 Compare October 2, 2026 02:41
@tony
tony deployed to docs-preview October 2, 2026 02:56 — with GitHub Actions Active
@tony
tony force-pushed the feat-reference-reading-layout branch from fe147a1 to a3db469 Compare October 2, 2026 06:42
@tony
tony deployed to docs-preview October 2, 2026 06:57 — with GitHub Actions Active
tony added 7 commits October 2, 2026 02:27
why: Python's generated search redirect has no article, so native shell
normalization rejected the complete assembly. Its root URL also lost the
selected preview, port and version.

what:
- Route native search pages to the owned port search page.
- Preserve the query and fragment with a static fallback link.
- Verify both Sphinx URL forms, repeat normalization and article guards.
why: Readers need to reach types and members without traversing package
paths. Literal name filtering misses queries such as Server panes and
new session and hides the distinction between Scala API variants.

what:
- Derive searchable identities, kinds and summaries from the API tree.
- Rank exact and qualified matches ahead of semantic reference order.
- Add category filters, keyboard navigation and visible retry behavior.
- Label Scala variants and keep Rust fuzz helpers in their own section.
- Verify native kinds across every port and exercise search in a browser.
why: Long qualified names dominate reference pages and crowded member
rows make their purpose difficult to scan. Readers still need exact
identities for copying, source lookup and durable links.

what:
- Lead pages with concise names, kind badges and useful summaries.
- Disclose full identities and provide exact-name copying with errors.
- Add stable section links and compact source/package metadata.
- Increase member spacing and wrap names within narrow columns.
- Verify copying, clipboard refusal and unique declaration anchors.
why: Long reference pages need a readable content column and direct
navigation to their sections and related declarations.

what:
- Add a responsive contents column and links from verified type relations
- Group member rows without changing their existing semantic order
- Keep section links aligned with the fields the declaration renders
- Verify anchors, active sections, ordering and responsive layouts

The outer loop passes in 41.30 seconds. An alphabetical-order mutation
fails the ordering regression check.
why: Namespace controls wasted space and native signatures linked syntax
and parameter bindings as though they were API references.

what:
- Align package names and exact-name copying beneath concise headings.
- Keep keywords and declaration bindings plain in native signatures.
- Resolve Scala and Kotlin builtins before JDK inventory aliases.
- Give overloads the full card width and preserve readable plain text.
- Check copy behavior, symbol links and responsive geometry in Chromium.
why: Readers need to understand the tmux objects managed by Server
before learning its transport implementation.

what:
- Extract the reviewed Java and Kotlin Server comments from 6e1fb29e.
- Refresh source paths and revision-bound example metadata.
- Preserve the native close, suspend and interoperability contracts.
why: Reduced opacity made keywords and parameter names look disabled.

what:
- Use the normal foreground color and full opacity for native syntax.
- Check signature contrast with scripting disabled in both themes.
@tony
tony force-pushed the feat-reference-reading-layout branch from a3db469 to 9a8be3e Compare October 2, 2026 07:34
why: The mobile toolbar stayed white in automatic dark mode before JavaScript initialized, and its drawer buttons did not work without JavaScript.

what:
- Use shared surface, text, border and hover colors in the mobile toolbar
- Provide native navigation disclosures when scripts are disabled
- Keep closed drawers inert from their first HTML render
- Check phone contrast, keyboard navigation and automatic theme colors
@tony
tony deployed to docs-preview October 2, 2026 08:21 — with GitHub Actions Active
@tony
tony merged commit 8a1d851 into main Oct 2, 2026
3 checks passed
@tony
tony deployed to docs-preview-cleanup October 2, 2026 08:41 — with GitHub Actions Active

This branch was successfully deployed

2 active deployments
docs-preview-cleanup — e76e0bba Deployed Oct 2, 2026 by tony via cleanup #60
docs-preview — e76e0bba Deployed Oct 2, 2026 by tony via publish-preview / publish #396
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