Skip to content

docs: landing redesign, design system, and page consolidation - #25

Merged
vboussot merged 2 commits into
mainfrom
docs/landing-redesign
Jul 5, 2026
Merged

docs: landing redesign, design system, and page consolidation#25
vboussot merged 2 commits into
mainfrom
docs/landing-redesign

Conversation

@vboussot

@vboussot vboussot commented Jul 5, 2026

Copy link
Copy Markdown
Member

Summary

Docs-only overhaul aimed at adoption: a redesigned landing, a site-wide design system, and a consolidation pass that removes duplicated pages so every topic has exactly one canonical home.

Landing & design system (5f28219)

  • New landing (index.rst): hero pairing a real Config.yml with the three CLI commands; a file → command → outputs mental-model table with the root keys visible (Trainer: / Predictor: / Evaluator:); three pillar cards; intent-based next-step cards; a full documentation index; MICCAI proof strip.
  • Design system (_static/custom.css): two-theme token palette sampled from the logo ink — teal as the brand voice, steel blue as the machine voice (code surfaces only), violet/coral/amber as category hues. Dark mode follows Shibuya's html.dark plus a prefers-color-scheme fallback.
  • Global content-page layer: typed admonitions (note/tip/warning/danger each get their hue), tables, code blocks, toctree lists and page leads inherit the design automatically — no per-page HTML.

Consolidation & orientation (55c9e7e)

Eleven redundant pages merged into their canonical homes, with every unique fact preserved:

Removed Residue folded into
usage/{training,prediction,evaluation} config_guide/{…} (+ new Running it sections: commands, RESUME, -tb, --evaluations-dir)
usage/remote-server, concepts/apps usage/apps (bundle anatomy + remote execution)
config_guide/patterns concepts/datasets
concepts/imaging-formats reference/components/storage-backends
contributing, architecture, usage/testing development (CI matrix, repository map, test loops)
reference/api/public-api reference/api/index
  • examples/segmentation, examples/synthesis and usage/docker are now single-sourced as MyST includes of the repository READMEs — no more diverging copies.
  • Orientation pass on every remaining page: a purpose lead ("what this page gives you, when you need it"), pruned Next steps (2–3 reasoned links), reading-order guidance on section indexes, and explicit success signals after each quickstart command.
  • Apps trust-model wording unified on the behaviour committed on main (requirements install is opt-in, off by default).

Verification

  • sphinx-build passes with zero broken-reference or orphan warnings (remaining warnings are the pre-existing autodoc import noise).
  • All landing links resolve; include pages render; each merge residue verified present in the built HTML of its surviving page.

Preview: pixi run build-docs then open docs/build/html/index.html.

vboussot added 2 commits July 5, 2026 15:20
New landing: hero pairing a real Config.yml with the three CLI commands, a
file -> command -> outputs mental-model table with visible root keys, three
pillar cards, intent-based next-step cards, a full documentation index, and
the MICCAI proof strip. The stylesheet gains a two-theme token system aligned
on the logo ink (teal brand voice, steel-blue machine voice, category hues)
plus a global content-page layer: typed admonitions, tables, code blocks,
toctree lists and page leads inherit the design automatically.
Merge eleven pages into their canonical homes: the usage workflow trio into
the config guide (which gains Running-it sections), remote-server and the
apps concept page into usage/apps, patterns into concepts/datasets,
imaging-formats into the storage-backends reference, and contributing,
architecture and usage/testing into development. Single-source the example
and docker pages as includes of the repository READMEs. Every page now opens
with a purpose lead and closes with pruned next-step links; section indexes
gain reading-order guidance; all cross-references retargeted (build is free
of broken-reference warnings).
@vboussot
vboussot merged commit 07f5645 into main Jul 5, 2026
2 checks passed
@vboussot
vboussot deleted the docs/landing-redesign branch July 5, 2026 13:31
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