Build Stages¶
Documentations is built in stages. By default, the following stages are executed when running repo docs:
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.