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/
    └── MyCompany/
        └── MyProduct/
            └── version_x/
                ├── config/
                │    ├── ubtrace_global_context.json
                │    ├── ubtrace_project.toml
                │    └── ubtrace_search_index.json
                └── docs/
                    ├── html/
                    │    ├── index.html
                    │    └── ...
                    └── ubtrace/
                        ├── needs.json
                        └── ...

The configuration file ubtrace_project.toml contains 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 builder does not introduce its own configuration syntax.

It relies entirely on the configuration options provided by Sphinx and its HTML builder. For ubTrace-specific settings (organization, project name, theme options, etc.), see Configuration.

Changelog¶

ubt_sphinx is versioned independently from the ubTrace platform. Releases are published on PyPI.

This changelog follows Keep a Changelog.

0.5.0 — 2026-03-10¶

Added¶

RST content extraction pipeline producing Document, Section, and TOCTree graph nodes with relationships.
Root index page automatically linked into the TOC tree.
Git data collection for per-document commit history, captured during the build and embedded in the output.

Changed¶

Decoupled ubt_sphinx from the monorepo-wide version sync so it can be versioned and released independently.
Replaced cssutils with tinycss2 for CSS processing.
ubtrace_build_kuzudb default changed from True to False (KuzuDB feature deprecated). Note: The Kuzu generation fails for new SN6/7 types. With the deprecation the plan is to remove it completely.
Git collector class refactored: data is now collected per-document during the Sphinx write phase, improving parallel-build (-j) performance. Git info is stored as a git_info key inside each .fjson output file instead of a separate API endpoint.

Fixed¶

Git collector and RST extraction now only run when the ubtrace builder is active, preventing unnecessary git-log calls and misleading console output with other builders (e.g. html).
Duplicate warnings for missing html_favicon / html_logo suppressed when the Sphinx config value was not provided.
Improved error handling and edge-case fixes in git data collection.
Increased unique ID length for section and directory generation to avoid collisions in large projects.
Added missing bs4 (BeautifulSoup) dependency.

Removed¶

Unused dependencies sphinxcontrib-plantuml and typing-extensions.

0.4.0 — 2025-09-08¶

Added¶

Git history collection for documentation projects: automatically collects per-file commit metadata (last edit timestamps, contributors, commit messages, URLs) during the build.

Changed¶

Enhanced directory structure creation for build output.

0.3.2 — 2025-08-21¶

Initial public release on PyPI.