octomy::apidocs::DocBookPage

Turns one page of QDoc's DocBook output into the markdown page the website and the in-app help both read.

Detailed description

Why DocBook, and why markdown

The API reference used to be two things: QDoc's HTML, complete and unframed, served as static files at a .html URL, and a markdown stub per class that carried only what QDoc's index holds — a brief, a header, an inheritance line. The stub linked out to the HTML for everything else. The owner ruled on 2026-10-11 that the markdown pages carry the whole reference and the HTML tree retires (api-reference §APD-A15).

QDoc's index cannot supply the rest: it records a member only when the member has its own block, and it never records a detailed description (§APD-M19). QDoc's DocBook output does. It is the same content as the HTML, in about 35 element names with no layout in them, so a converter can carry all of it.

Two passes

A link names an anchor on another page, and the anchor a member gets is decided when that page is read. So every page is parsed first and its member anchors collected into a Site, and only then is any page rendered.

Anchors that agree under both renderers

The site's renderer and the in-app help slug a heading differently: the first keeps a double hyphen where punctuation sat between two spaces, the second collapses it (DocLinkScan.hpp, "The anchor algorithm"). A member heading is therefore the member's name and, where two members share one, a kind word or an ordinal — text in which the two algorithms agree.

See also ConfigPlan.