Project Integration¶

ubTrace integrates and deploys user-specific documentation built with Sphinx. To ensure a stable and powerful setup, the following requirements must be met:

Your documentation uses Sphinx.
The Sphinx project includes the required config options in conf.py.
The documentation is built with the ubTrace Sphinx Builder.
For multi-project or multi-version setups, all generated documentation must be collected in a single folder, following a specific structure.

Most of these steps are handled automatically by the ubTrace Sphinx Builder, which uses sensible defaults and generates the required folder structure.

Folder Structure¶

ubTrace only requires a specific structure for the generated folders and files. No changes to your Sphinx project itself are needed.

ubTrace uses three identifiers:

Organization name
Project name
Version number

For example, this documentation is identified as: useblocks/ubtrace/1 Other examples: Sphinx/Sphinx-Needs-Demo/2, MyCompany/MyProduct/version_x

ubTrace supports two import methods (see Installation for details):

Pre-built CI output → place into input_build/
Sphinx source files → place into input_src/ (the builder compiles them automatically)

Example structure (pre-built CI output):

input_build/
├── MyCompany/
│   └── MyProduct/
│       └── version_x/
│           ├── config/
│           │    └── ubtrace_project.toml
│           └── docs/
│               └── ubtrace/
│                   ├── needs.json
│                   └── *.fjson
└── useblocks/
    └── ubtrace/
        ├── 1/
        │   ├── config/
        │   │    └── ubtrace_project.toml
        │   └── docs/
        │       └── ubtrace/
        └── 2/
            ├── config/
            │    └── ubtrace_project.toml
            └── docs/

Each project version contains two folders:

config: Stores project-specific configuration as ubtrace_project.toml. See Project Options.
docs: Documentation output – Sphinx-Needs data files (needs.json, *.fjson).

Note

The legacy ubtrace_server.toml file (still generated by the Sphinx builder) is no longer read by the NestJS backend. Project discovery is based solely on ubtrace_project.toml files.

Hint: Most of this structure is generated automatically by the ubTrace Sphinx Builder.

Project Configuration¶

Add the following values to your conf.py file:

ubtrace_organization
ubtrace_project
ubtrace_version

These values identify your project in ubTrace and are transferred to the project-specific ubtrace_project.toml file.

That’s all you need for a basic setup. For advanced options (authentication, layout, behavior), see Configuration.

Single-Project Integration¶

A valid single-project setup is automatically created by the ubTrace Sphinx Builder. Follow these steps:

Add the ubTrace Sphinx Builder to your project extensions:
```
# conf.py
extensions = ['ubt_sphinx', ... ]
```
Build the docs using the ubtrace builder, for example with make ubtrace. This build is typically faster than the standard HTML builder.
Import the build output into your ubTrace deployment:
```
make import-build SRC=./_build/ubtrace ORG=mycompany PROJECT=myproject VERSION=v1
```
The ub-worker service automatically detects the new data and loads it into the database. No restart is needed.

Multi-Project Integration¶

Sphinx and the ubTrace Builder do not know about other projects, so they cannot generate a multi-project structure automatically.

To set up multiple projects, import each one separately:

make import-build SRC=./projectA-output ORG=MyCompany PROJECT=ProjectA VERSION=v1
make import-build SRC=./projectB-output ORG=MyCompany PROJECT=ProjectB VERSION=v1

Alternatively, you can place Sphinx source files into input_src/ and let the ubtrace-builder service build them automatically:

make import-src SRC=./ProjectA ORG=MyCompany PROJECT=ProjectA VERSION=v1
make import-src SRC=./ProjectB ORG=MyCompany PROJECT=ProjectB VERSION=v1

The worker pipeline detects new or changed artifacts automatically – no manual restart is required. See Installation for the full import documentation.

This setup allows ubTrace to serve documentation for multiple projects and versions from a single instance, simplifying management and access.