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?”