8b461d99

By: Lucien Huber <im@lcnbr.ch>

restructure Linnest Typst API reference

User request:

PLEASE IMPLEMENT THIS PLAN:
# Cohesive API Reference Redesign

## Summary

Apply the approved compact, Typst-inspired design across the documentation while preserving each language’s useful native conventions. Shared improvements apply site-wide; structural redesign focuses on Python, native Rustdoc, and Linnest’s Typst API.

Start with `jj git fetch`, preserve the existing Python documentation work, create descendant changes for the redesign, and push the existing documentation bookmark only after validation.

## Implementation Changes

### Shared documentation UI

- Introduce a compact reference layout with an approximately 800px reading column, slim contextual navigation, and an optional right-hand table of contents only on sufficiently complex pages.
- Replace nested cards, strong purple borders, and heavy code shadows with whitespace and light dividers. Reserve plum for links, focus, selection, and active navigation.
- Standardize signature and example blocks:
  - language-appropriate syntax highlighting;
  - icon-only copy control visually inside the upper-right corner;
  - accessible label, keyboard focus, copied state, and graceful no-JavaScript fallback;
  - local scrolling for genuinely wide code.
- Fix site-wide mobile overflow for long links, inline code, tables, code blocks, and display MathML.
- Self-host STIX Two Math, including its license, and apply it explicitly to MathML.
- Demote oversized inventory statistics so useful reference content appears above the fold.
- Apply the shared spacing, typography, and code controls to authored and CLI pages without restructuring their content.

### Python reference

- Render the short symbol name as the H1 and show the fully qualified module path as secondary context.
- Keep `>>>` prompts in source docstrings for doctest/LSP compatibility, but strip prompts only from the parsed HTML example output.
- Keep runnable `main()` definitions at module level; the rendering pass must not introduce a nested wrapper.
- Organize pages consistently as signature, description, parameters, returns/raises, examples, and members/properties.
- Replace dense member cards with flat rows and dividers; keep defaults, types, overloads, and qualifiers visible.
- Rework the existing highlighting/copy implementation into the shared internal-icon treatment without adding a third-party JavaScript dependency.

### Rust reference

- Preserve native Rustdoc, including its search, sidebar, source links, trait/implementation hierarchy, and theme behavior.
- Pass a dedicated stylesheet through stable `rustdoc --extend-css`.
- Style primarily through Rustdoc variables and broad stable selectors so the customization remains resilient to Rust upgrades.
- Add a thin αLoop return/context bar through `--html-before-content`; do not replace or duplicate Rustdoc navigation.
- Match the shared typography, spacing, border, focus, and color system while retaining Rust-specific information density.

### Linnest Typst reference

- Keep `/guides/linnest/` as a concise narrative guide and preserve the complete standalone PDF manual.
- Refactor the canonical Typst documentation into reusable guide and API fragments so HTML reference pages and the PDF share one source.
- Add:
  - `/reference/typst/`
  - `/reference/typst/graph/`
  - `/reference/typst/layout/`
  - `/reference/typst/drawing/`
  - `/reference/typst/physics/`
  - `/reference/typst/subgraph/`
- Describe `layout` and `drawing` accurately as function groups rather than exported modules.
- List `curve` as a Kurvst re-export and link to its canonical Kurvst documentation instead of duplicating it.
- Use qualified, stable symbol anchors and search titles; exclude repetitive generic headings such as “Parameters” from search results while retaining their prose.

### Publishing and change organization

- Publish the generated root `search-index.json` from `scripts/update-docs-pages.sh` and fail publication checks when it is missing.
- Organize the work as three reviewable descendant jj changes: integrity fixes, shared/Python/Rustdoc UI, and Linnest Typst restructuring.
- Push the documentation bookmark after all three changes pass validation; do not rewrite or discard the existing working change.

## Interfaces and Compatibility

- No Rust, Python, or Typst runtime API behavior changes.
- New public documentation URLs are limited to the Typst reference routes above.
- The generated HTML gains a shared internal contract for language metadata, reference-page layout, code wrappers, and copy controls.
- The deployment artifact contract now explicitly includes the root search index.
- Existing URLs, dark mode, mobile navigation, Rustdoc functionality, and the standalone Linnest PDF remain supported.

## Test and Acceptance Plan

- Run, in repository-prescribed order:
  - `cargo check`
  - builder and documentation example tests;
  - documentation integrity checks;
  - the complete Nix documentation build for Python, Rust, and Typst.
- Add regressions covering:
  - root search-index publication and usable global search;
  - prompt-free rendered Python examples with source doctests unchanged;
  - short Python H1s and qualified paths;
  - internal accessible copy buttons and copied-state behavior;
  - required Typst routes, qualified anchors, and non-duplicated Kurvst content;
  - preserved Linnest PDF generation.
- Visually inspect representative Python module/symbol, Rustdoc crate/item, every Linnest Typst group, guide, CLI, search, and known overflow pages in light and dark themes at desktop and 390px mobile widths.
- Acceptance requires no page-level horizontal overflow, visible language-appropriate highlighting, working keyboard-accessible copy controls, readable MathML glyphs, functional Rustdoc navigation/search, and a materially shorter Linnest guide page.

Follow-up requests:

- “the box around the checkmark seems large and not centered”
- “and does the rustdoc styling match the rest?”

Timeline