Documentation

LIBRA provides targets for generating and checking API documentation (Doxygen) and project documentation (Sphinx). This page covers tool-specific behaviour and known issues. For the target reference, see Target reference.

General behaviour

Documentation targets do not depend on the main project build, so they can run in CI before or independently of the build step. Enable them with LIBRA_DOCS.

Both apidoc and sphinxdoc targets are attempted independently when running clibra docs. If a target is unavailable (e.g. doxygen is not installed), it is skipped with a warning rather than an error.

API documentation (Doxygen)

The apidoc target generates API docs from your source using Doxygen. Requires a docs/Doxyfile.in in the project root.

For checker configuration, third-party header gotchas, and the step-by-step workflow, see Documentation.

Project documentation (Sphinx)

The sphinxdoc target generates HTML project documentation using Sphinx. If the apidoc target exists, sphinxdoc depends on it so that API documentation is always current before Sphinx runs.

The Sphinx command used can be customized via LIBRA_SPHINXDOC_COMMAND if you need to pass additional arguments or use a wrapper script.

Currently, LIBRA only supports generating HTML output from Sphinx. Other builders (PDF, man pages, etc.) are not supported via the sphinxdoc target.