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 ubt_sphinx

The ubTrace builder is provided by the Python package ubt_sphinx.

Note

The instructions below were tested with pip 24.0, uv 0.10.9, and rye 0.44.0 on Python 3.12.3.

Minimum required versions:

  • pip ≥ 6.0 (--extra-index-url support)

  • uv ≥ 0.4.23 ([[tool.uv.index]] with explicit = true and [tool.uv.sources])

  • rye ≥ 0.2.0 ([[tool.rye.sources]] support)

pip

pip install ubt_sphinx --extra-index-url https://pypi.useblocks.com

uv

Configure the useblocks index in your pyproject.toml with explicit pinning:

[[tool.uv.index]]
name = "useblocks"
url = "https://pypi.useblocks.com"
explicit = true

[tool.uv.sources]
ubt-sphinx = { index = "useblocks" }
ubt-runtime = { index = "useblocks" }

Then run:

uv add ubt_sphinx
uv sync

Note

The explicit = true flag ensures uv only fetches ubt_sphinx and ubt_runtime from the useblocks index. All other dependencies (e.g. kuzu) resolve from PyPI automatically. This prevents dependency confusion without needing --index-strategy unsafe-best-match.

rye

Configure the useblocks source in your pyproject.toml:

[[tool.rye.sources]]
name = "useblocks"
url = "https://pypi.useblocks.com"

Then run:

rye add ubt_sphinx
rye sync

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.6.0 — 2026-03-27

Added

  • Traceability coverage pre-computation support.

Changed

  • Package status upgraded from Alpha to Beta.

Removed

  • KuzuDB integration — the deprecated ubtrace_build_kuzudb option and all Kuzu graph database code have been removed. Build output is now handled entirely by PostgreSQL + Elasticsearch on the server side.

0.5.0 — 2026-03-10

Added

  • RST content extraction pipeline producing document, section, and table-of-contents graph nodes with relationships.

  • Root index page automatically linked into the TOC tree.

  • Per-document git history (last edit timestamps, contributors, commit messages) captured during the build and embedded in the output.

Changed

  • ubt_sphinx is now versioned and released independently from the ubTrace platform.

  • Replaced cssutils with tinycss2 for CSS processing.

  • ubtrace_build_kuzudb default changed from True to False (KuzuDB output is deprecated and will be removed in a future release).

  • Git history is now collected per-document during the Sphinx write phase, improving parallel-build (-j) performance. Git info is stored inside each .fjson output file.

Fixed

  • Git collector and RST extraction now only run when the ubtrace builder is active, preventing unnecessary processing with other builders (e.g. html).

  • Suppressed duplicate warnings for missing html_favicon / html_logo when not configured.

  • Increased unique ID length for section and directory generation to avoid collisions in large projects.

  • Added missing bs4 dependency.

Removed

  • Unused dependencies sphinxcontrib-plantuml and typing-extensions.

0.4.0 — 2025-09-08

Added

  • Per-document git history collection: automatically captures last edit timestamps, contributors, commit messages, and URLs during the build.

Changed

  • Enhanced directory structure creation for build output.

0.3.2 — 2025-08-21

  • Initial public release.