API reference

The API reference is one page per documented C++ class, struct and namespace in OctoMY™. QDoc, the Qt documentation generator, reads the docstrings in the source, and the apidocs tool turns its output into these pages.

• Every class, with a one-line brief for each
• Every namespace
• Overview: the libraries, what each one holds, and where to start

What a page holds

Each class page holds:

• the class brief, and the header that declares the class
• its base classes and the classes that inherit it, linked
• its group
• its detailed description, with the lists, tables, code and links the docstring holds
• every member that has its own documentation: the name, the signature and the text
• a live picture, when the class is a registered widget

A link to a Qt class goes to Qt's own reference. A link to an explanation or a how-to goes to that page here.

Member documentation is sparse, and that is a choice of the project. QDoc documents a member only when the member has its own documentation block. The project's docstring rules make the class block required and a member block optional, so most pages have a detailed description and no member section.

It is generated, and it is not in git

The pages under classes/, namespaces/ and overview/ are build output. They are not tracked, and a fresh clone does not have them. Generate them with one command:

kiln apidocs

The run takes about seven minutes. It needs the source tree and a Qt documentation install.

The reference was tracked until 2026-10-07, and that is why it went stale: a regeneration wrote about 1,500 files into every diff, so nobody ran one. The reference was regenerated once in 6,113 commits.

Full procedure, and what to do when the run fails: Regenerate the API reference.

The run reports, so a bad run fails

Two numbers fail the build rather than writing half an answer:

Both come from a measured run, and both are declared in the build. The ceiling only ever moves down.

This matters because the generator used to report nothing. On 2026-10-07 a run produced 374 class pages where the tracked tree held 919, took 27 minutes 37 seconds, and exited 0. The cause was the configuration, not the docstrings: it handed QDoc about 10,000 vendored files it must not read.

The same pages in the application

These pages are markdown, so the application's own help system carries them too. A class is findable on a machine with no browser and no network, and a widget's page shows the widget, rendered live.

Until 2026-10-11 the full reference was a separate tree of HTML pages, without the site's frame, at addresses that ended in .html. Those addresses now lead to the page of the same class here.