Build Stages

Documentations is built in stages. By default, the following stages are executed when running repo docs:

graph LR clean --> prepare --> doxygen --> exhale --> sphinx

If multiple projects are defined in repo.toml, each stage will complete for each project before the stage is executed.

When running repo docs, the stage to run can be specified with the --stage flag. For example, to just run Doxygen:

repo docs --stage doxygen

--stage can be specified multiple times (order does not matter):

repo docs --stage clean --stage doxygen

Tip

Selectively running stages can greatly increase iteration time. For example, when authoring overview documentation, just run the sphinx stage to build only the .rst files that have changed. When writing API documentation, just run the doxygen stage to quickly find and fix Doxygen warnings/errors.

Stage Reference

The full list of stages are as follows:

coverage

Prints the numbers of C++ headers that have been included in the API documentation.

clean

Cleans any output from the previous build.

This stage runs by default.

prepare

Creates the output directory and build information for subsequent build steps.

This stage runs by default.

doxygen

Runs Doxygen on any file specified by doxygen_input in repo.toml. Doxygen is run only if input files are specified.

Doxygen is a tool which extracts API documentation information from C++. See Omniverse Doxygen Guide for details.

This stage runs by default.

exhale

Create one or more .rst files for entities found by Doxygen. For example, a dedicated .rst is created for each header, class, function, etc. This stage runs only if doxygen_input is defined in repo.toml.

This stage runs by default.

sphinx

Converts .rst files to HTML. This stage only rebuilds files that have changed.

publish

Publish built documentation to the specified location in repo.toml. See Publishing Documentation for more information.