Adding a Doxygen document

Continuing from Your first document: the same project, one more document, this time from the other toolchain — still standalone, with no registry and no cross-references to the runbook document from the previous tutorial. That comes in Cross-referencing two documents.

Lay out the document

A Doxygen document’s folder is named for its id, the same as a Sphinx document’s:

$ mkdir -p doc/widget

doc/widget/mainpage.md:

# Widget API

Doxygen document for the widget API.

doc/widget/Doxyfile.in:

PROJECT_NAME           = "Widget API"
PROJECT_BRIEF          = "The widget API"

OUTPUT_DIRECTORY       = @DOXY_OUT@
CREATE_SUBDIRS         = NO

INPUT                  = @DOXY_SRC_DIR@/mainpage.md \
                         @MY_PROJECT_BASE@/api/widget.h

USE_MDFILE_AS_MAINPAGE = @DOXY_SRC_DIR@/mainpage.md
RECURSIVE              = YES
FILE_PATTERNS          = *.h *.c

EXTRACT_ALL            = YES
OPTIMIZE_OUTPUT_FOR_C  = YES

GENERATE_HTML          = YES
GENERATE_LATEX         = NO

configure_file(... @ONLY) substitutes @DOXY_OUT@ and @DOXY_SRC_DIR@ — engine-provided — and @MY_PROJECT_BASE@, which is your CMake variable from Your first document’s CMakeLists.txt, referenced here exactly the way you’d reference any of your own. Nothing about HTML_OUTPUT, GENERATE_TAGFILE or GENERATE_XML belongs in this file: the engine appends all three itself, after this template is expanded, and a line setting one here would simply be discarded — see The registry schema’s list of engine-owned Doxyfile keys.

Point it at some real input — an api/widget.h with a documented function or two, anywhere Doxygen’s FILE_PATTERNS/INPUT above will find it.

Add the target

One line in doc/CMakeLists.txt, after the add_sphinx_target call from Your first document:

add_doxygen_target(widget)

The factory’s argument is the document’s id (widget); it derives the source folder (doc/widget/) and the deploy path (deploy/html/widget/) from it directly, with nothing prepended. If you wanted a dox- prefix on the folder, the target name and the deploy path, you would write it into the id itself and call add_doxygen_target(dox-widget) against a doc/dox-widget/ folder — the engine holds no opinion either way.

Build it

$ cmake --build build

all-docs now builds both documents. Open build/deploy/html/widget/index.html alongside build/deploy/html/runbook/index.html from the previous tutorial — two independent documents, from two different toolchains, in one build, still with no link between them: each one’s navigation and cross-reference machinery only activates once a registry names them as peers.

What’s next

Cross-referencing two documents introduces documents.yaml and turns these two standalone documents into a proper document set: a shared navigation sidebar, and a real cross-reference from the Sphinx document into the Doxygen one.