Sphinx ubTrace Builder

The ubTrace builder generates an optimized build output from Sphinx, including documentation, configuration, and metric files.

A dedicated Sphinx builder named ubTrace builder is provided for this purpose.

Performance Note: The ubTrace builder is significantly faster than the standard HTML builder—up to 50% faster in some scenarios.

Installation & Configuration

Install the builder with:

pip install ubt_sphinx

Activate the builder by adding it to the extensions list in your conf.py file:

extensions = [
   # other extensions
   "ubt_sphinx"
]

For detailed configuration options, see the project options section in configuration.

Usage

Once installed and configured, you can build your documentation using the builder name ubtrace.

Example:

make ubtrace
# Or for more control:
sphinx-build -b ubtrace . _build/ubtrace

Output Structure

After building, the _build/ubtrace folder will contain the following structure:

_build/
└── ubtrace/
    ├── ubtrace_server.toml
    └── MyCompany/
        └── MyProduct/
            └── version_x/
                ├── config/
                │    ├── ubtrace_global_context.json
                │    ├── ubtrace_project.toml
                │    └── ubtrace_search_index.json
                ├── db/
                └── docs/
                    └── ubtrace/
                        ├── index.fjson
                        └── # many more files...

The configuration files ubtrace_server.toml and ubtrace_project.toml contain settings that can be changed and extended using options from Configuration.

The output can be used directly by the ubTrace server. Integration details are described in Project Integration.

Note

It is important to keep the internal structure of _build/ubtrace unchanged. ubTrace requires the correct placement of files; otherwise, features like Search, Analysis, or even documentation delivery may not work properly.

Configuration

The ubTrace server does not provide its own configuration options.

It relies entirely on the configuration options provided by Sphinx and its HTML builder.