Skill Toc Tree

Qt Documentation Topic Tree Reference

How Qt documentation pages become visible — and ordered — in the navigation tree: the QCH contents in Qt Assistant/Qt Creator and the sidebar on doc.qt.io.

When to Use

• A new manually written page must appear in the tree
• Creating module documentation from scratch (new module)
• A page builds fine but is missing from the sidebar or QCH contents
• Pages appear in the wrong order or at the wrong nesting level
• Build log shows Failed to find table of contents with title or Failed to find <P>.indexTitle
• Auditing a module for orphan pages

The Module Tree

A module's tree is declared by qhp.<Module>.subprojects. Item order is significant — it is the order of the branches in the tree:

qhp.QtQuick.subprojects = manual examples qmltypes classes

puts the manually combined nodes first, then selector-generated examples, then QML types, then the C++ API. Conventional branches — modules use whichever subset applies:

The rule this skill enforces: selector-based branches are collected automatically; manually written pages are not. A manually written page is in the tree only if it is listed on <module>-toc.qdoc.

The tree visible in the QCH is the same tree that appears on the website. Preview it locally by opening the compiled .qch in Qt Creator's help viewer or in Qt Assistant.

Small-module variant: a module with one or two doc topics can skip the manual branch and TOC page. A subproject whose indexTitle is the one topic and whose selectors match nothing yields a single tree entry (QtSpatialAudio: subprojects.overview.indexTitle = Spatial Audio Overview, selectors = group:none; since QDoc 6.9 the documented form is selectors = none).

For subproject properties and selectors, read references/qhp-subprojects.md.

Groups Are Lists, Not Navigation

\group, \ingroup, \annotatedlist, and \generatelist create topic listings on pages. Group membership does not place a page in the tree. The \group page itself, however, should be listed on the module's TOC page like any other manually written page.

For group and list command syntax, read skill-qdoc/references/group-and-organization.md.

The Module Contract

Five qdocconf values must each match a \title exactly. Qt Quick (qtdeclarative/src/quick/doc/qtquick.qdocconf) exercises all of them:

The last two name the same page: one \list on qtquick-toc.qdoc drives both the previous/next page order (navigation.toctitles) and the manual branch of the tree (indexTitle + type = manual).

The <module>-toc.qdoc Page

/*!
    \page qtquick-toc.html
    \title Qt Quick module topics

    \list
    \li \l {Getting started with Qt Quick applications}{Getting Started}
        \list
            \li \l {First Steps with QML}
        \endlist
    \li \l {Important Concepts In Qt Quick - The Visual Canvas}{Visual Canvas}
    \endlist
*/

• Nesting depth = tree depth; list order = page order (previous/next).
• Link by page \title; an optional second argument sets the visible tree label.
• Tree items must be \l links (or a \generatelist). A plain-text \li item is not displayed in the tree.
• Use \generatelist [descending] <group> (QDoc 6.11+) to add numerous homogeneous topics that need no subitems — linter diagnostics, what's new items. See references/toc-page.md.

For navigation.toctitles semantics and worked examples, read references/toc-page.md.

The Framework Tree

qtdoc/doc/config/style/tree_config.xml holds the root structure of the Qt Framework documentation (not Qt Creator or other projects). It specifies how the module trees are merged into the single tree on the website: <node toc="qtcore"/> inserts a module's tree, parent_url grafts it under another module's page, and <node title= href=> creates folder nodes. The file carries a comprehensive doc comment on its own format.

A module without a manual branch or TOC page still appears here — its tree is just the selector-generated branches (many <node toc=> entries have no matching *-toc.qdoc).

For the node format and the new-module procedure, read references/tree-config-xml.md.

Procedure A — Add a Manually Written Page

1. Locate the module's TOC page: the file whose \title matches navigation.toctitles (conventionally <module>-toc.qdoc).
2. Add an \li \l {Page Title} entry at the intended depth and position. Position sets previous/next order; depth sets nesting.
3. API and example pages need nothing — selectors collect them.
4. Rebuild; confirm no Failed to find table of contents warning and that the page appears in the .qch contents.

Procedure B — Create Module Docs from Scratch

For new modules only. Two sides, two repositories:

1. Module side: landing page (<module>-index.qdoc), \module and/or \qmlmodule pages, the TOC page, the five matching qdocconf values (see The Module Contract), and qhp.<Module>.subprojects in tree order. Small modules may use the single-topic subproject instead.
2. qtdoc side: add a <node toc="<module>"/> entry to qtdoc/doc/config/style/tree_config.xml, with parent_url if the module belongs under another module's node.

Skipping step 2 produces no warning — the module simply never appears in the website tree.

Procedure C — Orphan Audit

A manually written page is in the tree iff it is reachable from the module's TOC page. Group membership does not count.

1. Enumerate manually written pages:

   grep -rh "^[[:space:]]*\\\\page " src/<mod>/doc/src \
     --include="*.qdoc" | awk '{print $2}' | sort > /tmp/pages.txt
   

2. Collect their titles (a second grep for \title in the same files). Subtract auto-collected node types (\example, \class, \qmltype pages need no TOC entry) and every branch root: the landing page (navigation.landingpage), the TOC page itself, and every qhp.<P>.subprojects.*.indexTitle value — those pages are the roots of the selector branches, already in the tree.
3. Extract every \l {Title} from <module>-toc.qdoc (including nested lists) and compare.
4. Report each unlisted page as ORPHAN. Flag \group pages missing from the TOC page. QDoc itself never warns about orphans.

Warning Catalogue

Exact strings to grep in build logs:

Silent Failures

No warning is emitted for any of these:

• Manually written page never added to the TOC page — builds clean, absent from every tree.
• A plain-text \li item (no \l) in the TOC list — silently omitted from the tree.
• Module missing from tree_config.xml — invisible on the website.
• A subproject defined but not listed in qhp.<P>.subprojects — the block is ignored (live example: qtdoc's examples block).
• \generatelist inside a TOC list on QDoc < 6.11 — no navigation links are generated for the group members.
• \ingroup consumes the rest of the line — a trailing comment silently becomes part of the group name.

Reference Materials

Owned Elsewhere — Do Not Duplicate

External References

• QDoc Manual: navigation
• QDoc Manual: Creating Help Project Files

Version History

• 1.0.0 (2026-08-14): Initial version — module tree subprojects, TOC page, framework tree, orphan audit