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]] support)
rye ≥ 0.2.0 ([[tool.rye.sources]] support)

pip¶

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

uv¶

Add the useblocks index to your pyproject.toml:

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

Then run:

uv add ubt_sphinx
uv sync

uv’s default first-index strategy queries the useblocks index for every package and falls through to PyPI for anything it doesn’t host, so ubt_sphinx and ubt_runtime resolve from useblocks while all other dependencies resolve from PyPI automatically.

Tip

Multi-index setups. If you also use a corporate / internal PyPI mirror, declare it before the useblocks index. uv walks indexes in declaration order and falls through on 404, so internal packages resolve from your mirror, ubt_* packages from useblocks, and everything else from PyPI:

[[tool.uv.index]]
name = "company"
url = "https://pypi.company.internal/simple/"

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

For strict isolation of internal packages (defense against dependency-confusion attacks), keep explicit = true on the corporate index and add a [tool.uv.sources] entry per internal direct dependency. Scope the explicit flag to the corporate index only — the useblocks index does not need it.

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.

Project Identity (organization, project, version)¶

The builder writes its output under a three-level folder layout derived from three required conf.py keys:

# conf.py
ubtrace_organization = "mycompany"   # organization slug
ubtrace_project      = "my-product"  # project slug
ubtrace_version      = "v1"          # version identifier

These values become the path segments that the ubTrace server uses to locate the artifact, both for folder-based imports (input_build/<org>/<project>/<version>/) and for the HTTP ingest endpoint (/v1/ingest/<org>/<project>/<version>).

Warning

The three keys ubtrace_organization, ubtrace_project, and ubtrace_version must match the path segments of the ingest URL exactly – including case. A mismatch is the single most common cause of an otherwise unexplained 400 Bad Request from /v1/ingest/...: the archive ships its own ubtrace_project.toml identity record, and the server rejects uploads whose folder / conf.py identity does not equal the URL segments.

See TOML identity check for the exact comparison rules and Ingest Documentation via API for an end-to-end example that keeps conf.py and the upload URL in sync via a single UBTRACE_VERSION environment variable.

The same three identifiers also drive multi-project routing on the ubTrace server – the values you pick here are the slugs your users will see in the project switcher and the URL bar:

Project Integration – folder layout, ubtrace_project.toml flow, and how the worker discovers your artifact.
Multi-Project Support – how organization / project / version identifiers power multi-tenant deployments.
Project Options – full reference for ubtrace_organization, ubtrace_project, and ubtrace_version.

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.

Warning

ubtrace_organization, ubtrace_project and ubtrace_version must match the ingest URL path segments exactly. See Project Identity (organization, project, version) for the full explanation and cross-references.

ubTrace compatibility¶

ubt_sphinx is versioned independently from the ubTrace platform, but the two are coupled by a data-format contract: ubt_sphinx writes the build artifacts (needs.json, the ubtrace output tree, configuration files, and per-document git history) that the ubTrace server ingests. A mismatched ubt_sphinx version can produce output that the server rejects, parses incorrectly, or treats as missing data.

For each ubTrace release we therefore publish a recommended ubt_sphinx version. Customers should pin to the recommended version in their CI pipeline.

As of today, ``ubt_sphinx 0.8.1`` is the recommended version for ubTrace 1.6.0. The 0.8 line adds automatic source_meta emission into needs.json, enabling per-need source navigation without server-side configuration; 0.8.1 additionally restores the sphinx.builders entry point (so the builder runs without ubt_sphinx in conf.py extensions) and keeps needs on symlinked pages from being dropped. For ubTrace 1.3.x and earlier, ubt_sphinx 0.7.1 remains the recommended version.

Recommended `ubt_sphinx` version per ubTrace release¶
ubTrace release	Recommended `ubt_sphinx`	Notes
1.6.0	0.8.1	Native pairing — restores the `sphinx.builders` entry point and preserves needs on symlinked pages. Widens the `serializinghtml`, `rcssmin`, and `docutils` constraints.
1.4.0	0.8.0	Native pairing — adds `source_meta` for per-need source navigation. Requires `repo_url` and `edit_uri` in `ubtrace_theme_options` (see edit_uri).
1.3.0	0.7.1	Native pairing — Sphinx 9 compatibility and the reproducible-wheel release of the 0.7 line.
1.2.x	0.7.1	Forward-compatible with the 1.2 server. Older 0.6.x builds still work but no longer receive fixes.
1.1.x	0.7.1	Forward-compatible with the 1.1 server. Older 0.6.x builds still work but no longer receive fixes.

Note

The data contract is designed to be forward-compatible: newer ubt_sphinx releases that don’t change the on-disk format can be used with older ubTrace servers. We update this table whenever a new ubt_sphinx release changes the recommendation for any supported ubTrace version.

Changelog¶

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

This changelog follows Keep a Changelog.

0.8.1 — 2026-06-23¶

Fixed¶

The ubtrace builder runs again without ubt_sphinx in the conf.py extensions list (restored sphinx.builders entry point).
Needs on pages reached through a symlink are no longer dropped from needs.json (fixes spurious 404s for those needs).

Changed¶

Widened the serializinghtml, rcssmin, and docutils dependency constraints.

0.8.0 — 2026-05-15¶

Added¶

Automatic source_meta emission: the builder now writes source file path and line number into each need’s metadata in needs.json. This enables per-need “Edit source” navigation in the ubTrace frontend without any server-side configuration.

Changed¶

Requires repo_url and edit_uri in ubtrace_theme_options for source navigation links. A new ubtrace_default_branch option controls the branch placeholder in edit_uri.

0.7.1 — 2026-05-01¶

Changed¶

Reproducible wheel builds: ubt_sphinx and ubt_runtime wheels are now byte-stable across rebuilds, so lockfile hash verification (uv sync, pip install --require-hashes) no longer breaks on republished releases.
Released as part of a coordinated ubt_runtime 0.6.0 line; pinning ubt_sphinx==0.7.1 resolves to the new, immutable runtime wheels.

0.7.0 — 2026-04-30¶

Added¶

Sphinx 9 compatibility (uv-driven test matrix).

Fixed¶

Minifier crashed with IsADirectoryError on the build output directory.

0.6.1 — 2026-04-10¶

Fixed¶

Replaced jsmin with rjsmin for offline bundle compatibility.

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.

Sphinx ubTrace Builder¶

Installation & Configuration¶

Install ubt_sphinx¶

pip¶

uv¶

rye¶

Project Identity (organization, project, version)¶

Usage¶

Output Structure¶

Configuration¶

ubTrace compatibility¶

Changelog¶

0.8.1 — 2026-06-23¶

Fixed¶

Changed¶

0.8.0 — 2026-05-15¶

Added¶

Changed¶

0.7.1 — 2026-05-01¶

Changed¶

0.7.0 — 2026-04-30¶

Added¶

Fixed¶

0.6.1 — 2026-04-10¶

Fixed¶

0.6.0 — 2026-03-27¶

Added¶

Changed¶

Removed¶

0.5.0 — 2026-03-10¶

Added¶

Changed¶

Fixed¶

Removed¶

0.4.0 — 2025-09-08¶

Added¶

Changed¶

0.3.2 — 2025-08-21¶

Install `ubt_sphinx`¶