Story: Qt help system from the user manual
Table of Contents
This page documents a story in Sprint 20. It captures the goal, current status, acceptance criteria, and the tasks that compose it.
Goal
Give the Qt desktop application a built-in help system whose content is
the existing user manual — no second source of truth. A build step turns
the manual's exported HTML into a Qt help collection (.qch), and the
application ships and opens it from the Help menu with a contents tree, a
keyword index and full-text search, so users get offline, searchable help
that tracks the manual automatically.
Status
| Field | Value |
|---|---|
| State | DONE |
| Parent sprint | Sprint 20 |
| Now | Nothing. |
| Waiting on | Nothing. |
| Next | Nothing. |
| Last touched | 2026-06-10 |
Acceptance
- A build target produces
user_manual.qch(+ collection.qhc) from the manual, reusing the org→HTML export rather than a second content source. - The exported help HTML is self-contained: relative asset paths, bundled CSS/images, and a plain stylesheet that renders cleanly in QTextBrowser.
- The Qt app links
Qt6::Helpand has a HelpViewer: contents tree + index + full-text search in a sidebar, content in a QTextBrowser. - Help → User Manual opens the viewer (MDI subwindow, like About); the
.qchis located/packaged with the app and found at runtime. - The help system itself is documented in the manual.
Tasks
| Task | State | Start | End | Description |
|---|---|---|---|---|
| Scaffold story | DONE | 2026-06-08 | 2026-06-08 | Story, tasks, sprint wiring, scaffold PR. |
| Produce a self-contained manual HTML export for Qt help | DONE | 2026-06-08 | 2026-06-08 | Help-friendly export: relative assets, bundled CSS/images, plain stylesheet. |
| Generate the .qch help collection via qhelpgenerator | DONE | 2026-06-08 | 2026-06-08 | .qhp manifest from the chapter ToC; compile to .qch/.qhc; build target. |
| Add a HelpViewer widget backed by QHelpEngine | DONE | 2026-06-08 | 2026-06-09 | Link Qt6::Help; QHelpEngine + contents/index/search sidebar + QTextBrowser. |
| Wire the help viewer into the Help menu | DONE | 2026-06-09 | 2026-06-10 | User Manual action → MDI subwindow; package/locate the .qch; document it. |
Decisions
- Native Qt Help over a web view
- Chosen the capture's
.qch+QHelpEngineapproach over embeddingQWebEngineView. It adds only the lightQt6::Helpmodule (no Chromium), works fully offline, and gives a contents tree, keyword index and full-text search for free. The trade-off —QTextBrowserrenders only a subset of HTML/CSS — is absorbed by the help-specific export (task 1), which produces a plain, self-contained stylesheet rather than the web theme. External-browser (QDesktopServices) was rejected as not in-app; web-engine fidelity was not worth the dependency weight for reference documentation. - Single source of truth
- Help content is the manual; the export is a transform, never a copy. Re-running the build refreshes help.
Out of scope
- Context-sensitive (F1 / "What's This?") help mapping individual windows to manual sections — a natural follow-up once the viewer exists.
- Authoring new manual content — this story plumbs the existing manual into the app; chapters are written by the manual stories.
- Online/remote help hosting — the .qch ships with the app, offline.