Documentation Site workstream

[JArmandoAnaya]

Cross-pillar workstream tracked under milestone P2 — Roads & Lanes, decided in ADR-0009 and specified in the roadmap's Documentation site section.

Grows the in-app Help system seeded by help-s1/help-s2 into a published, versioned web manual without giving up in-app F1.

The decision in one screen

1. Two tiers, one bridge. The Qt Help pipeline is kept permanently; its scope narrows to what it does best. The split is by the role of the content, not by format.

Tier	Source	Rendered by	Syntax budget
Reference	docs/user-guide/reference/	.qch (in-app, F1) and the site	Strict CommonMark subset — QTextBrowser renders a limited HTML/CSS subset
Guides	docs/user-guide/guides/, docs/user-guide/tutorials/	The site only	Markdown + Starlight asides; MDX/JS deferred as long as possible

Reference pages are short per-tool/per-panel pages: what it does, parameters, shortcuts, a couple of paragraphs. The helpId() mapping and the tool/panel coverage test apply to the reference tier only. Each reference page ends with a "full guide" link that the in-app viewer opens in the external browser (QDesktopServices::openUrl) into the packaged HTML manual. F1 gives the instant answer; one click gives the rich version.

Why: forcing all content through both pipelines condemns everything to the lowest-common-denominator Markdown QTextBrowser accepts, and produces defects like #292 and #297. The tiered model shrinks the dual-source surface to the reference pages alone.

2. Single source. docs/user-guide/ stays the sole authored source. The site ingests it at build time via a Node adapter script that copies content into Starlight's content dir, synthesizes title frontmatter from the first H1, rewrites relative links/images for site routing, and fails on broken links. Adapter output is generated and gitignored; hand-editing it is forbidden.

3. Tooling. Astro Starlight in a new top-level docs-site/ folder (docs/ stays the contributor source of truth; docs-site/ is tooling). Node LTS pinned (engines + .nvmrc), package-lock.json committed, npm ci in CI, all npm deps MIT/BSD/Apache-2.0-compatible. Site CI on Linux runners only. The C++/CMake build stays Node-free — CMake never invokes npm; packaging jobs build the manual first and hand the prebuilt folder to CMake behind ROADMAKER_BUNDLE_MANUAL (default OFF). Theme reuses the graphite + amber palette.

4. Two build modes. Local reader (ships in each release): opens from file://, no server — file-format output, fully relative refs, search disabled (Pagefind can't index file:// in mainstream browsers) with a note on the local landing page; CI fails if any root-absolute path survives. Web: standard output, search on, configurable --base=/<segment>/. Install layout: RoadMaker.app/Contents/Resources/manual/ (macOS), share/roadmaker/manual/ (Linux), manual/ beside the exe (Windows). Help-menu action opens manual/index.html in the default browser, degrading to a pointer at the web docs on dev builds. F1 untouched. Embedding QWebEngineView is explicitly rejected — Chromium for a problem the OS browser solves for free.

5. Versioned publishing. Actions assembles dev/ (from main), vX.Y.Z/ (per release tag), latest/, a root redirect, and a root versions.json driving a header version dropdown, onto a publishing branch that AWS Amplify Hosting serves prebuilt (Amplify does not build from source — tag-driven multi-version assembly is Actions territory). Workflows only react to tags; nothing here ever creates a tag or a release. All Amplify console setup and publishing is the maintainer's; sprints deliver amplify.yml, workflows, and a runbook. Must work with dev/ alone today and grow versions when v0.1.0 lands.

6. Release gate. Gate point 4 ("Docs synchronized") now also requires: Starlight green in CI; the maintainer hand-verifies the local reader opens from file:// on macOS/Linux/Windows; the Help-menu action works in the packaged app; bridge links resolve in both directions.

Sprints

Sequential: docs-s1 gates everything; docs-s2 and docs-s3 are independent of each other but land in order.

• docs-s1: tier restructure + Starlight scaffold + adapter + CI validation #345 — docs-s1: tier restructure + Starlight scaffold + adapter + CI validation
• docs-s2: local reader build + release packaging + Help-menu action + bridge links #346 — docs-s2: local reader build + release packaging + Help-menu action + bridge links
• docs-s3: versioned web publishing #347 — docs-s3: versioned web publishing
• docs-s4: hardening + authoring guide + close-out #348 — docs-s4: hardening + authoring guide + close-out

Status (2026-08-02): COMPLETE — all four sprints merged. #345 (tier
restructure + Starlight scaffold + adapter), #346 (local reader + release
packaging + Help-menu action + bridge links), #347 (versioned web publishing)
and #348 (hardening + authoring guide + close-out) are closed via
squash-merged PRs #560, #561 and #562 with green CI. The docs publish
workflow has run for real: the docs-published branch exists and carries
dev/, the root redirect, versions.json (latest: null, default: dev)
and amplify.yml.

What remains is not sprint work. Two release-gate items are maintainer
hand-runs and are recorded at the
release gate,
not here: the local reader opened from file:// in a browser on macOS, Linux
and Windows, and the Help-menu "open manual" action in a packaged app.
Creating the hosting app against the docs-published branch and attaching the
domain is likewise the maintainer's, per
the runbook.

#297 is untouched and remains open, as every sprint in this workstream
stated. The <kbd> normalisation is specified by
the authoring guide
and still needs its own PR to apply; the objects-signals.md split and the
ToolId coverage hole noted below are likewise still open as separate work.

How this relates to existing work

• help-s1: Qt Help pipeline + in-app viewer #265 help-s1 (Qt Help pipeline + in-app viewer, merged) — this workstream keeps everything it built and narrows its input to docs/user-guide/reference/; the .qch pipeline, the in-app viewer, and the theme are permanent, not transitional.
• help-s2: F1 context help, coverage test, seed tutorials #266 help-s2 (F1 context help, coverage test, seed tutorials, merged) — its tool/panel coverage gate survives the restructure and becomes reference-tier-only; its seed tutorials move out of the .qhp path into the guides tier, which is what removes their dual-pipeline constraints.
• Help pipeline: tutorial pages' parent-relative links rewrite to wrong guide-root URLs #297 (tutorial parent-relative links rewrite to guide-root URLs, open) — the tiered model reduces its blast radius by taking tutorials out of the .qhp path, but does not fix it: reference pages still link to each other relatively and the rewriter is still wrong. Help pipeline: tutorial pages' parent-relative links rewrite to wrong guide-root URLs #297 stays an independent P2 bug with its own fix and regression test. No sprint in this workstream closes it.

Noted, deliberately not in scope

Recorded here so the ideas are not lost and do not leak into a sprint:

1. Coverage-gate hole in the tool enum. ToolId declares StopLine, JunctionSpan, and JunctionSurface after Corner (editor/src/tools/tool.hpp), but kToolPages stops at Corner and test_help_registry.cpp's loop bound is <= ToolId::Corner — so those three tools have no help page and the gate does not catch it. A real defect in the help gate; wants its own P4/help issue, not a docs-site sprint.
2. objects-signals.md (193 lines) is genuinely mixed — a reference head, a developer "authoring in Python" section, four tool walkthroughs, and a junction-markings table. docs-s1 classifies and moves whole pages only; splitting it is separate content work.
3. <kbd> inline HTML appears on 7 pages while most reference pages use backticks for the same purpose. Normalizing would make every reference page pure CommonMark — a candidate cleanup for the docs-s4 authoring guide to specify, and a separate PR to apply.
4. Unreferenced assets docs/user-guide/img/gs1_hero.png and workflow.gif are linked by no page (and a .gif will not animate in QTextBrowser).
5. docs/README.md's conventions section says the tree is "structured so a static-site generator (e.g. MkDocs) could be adopted later" — stale once ADR-0009 lands; docs-s4 fixes it.