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

This allows you to create an output folder containing multiple projects from different organizations and versions.

Example structure:

output
├── MyCompany
│   └── MyProduct
│       └── version_x
│           ├── config/
│           │    └── ubtrace_project.toml
│           └── docs/
│               ├── html/
│               └── ubtrace/
│                   ├── needs.ndjson
│                   ├── needs-coverage.ndjson
│                   └── needs-relations.ndjson
└── useblocks
    └── ubtrace
        ├── 1/
        │   ├── config/
        │   │    └── ubtrace_project.toml
        │   └── docs/
        │       ├── html/
        │       └── 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 – HTML files and NDJSON analytics data (needs, coverage, relations).

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.
Copy the build output into the input/ directory of your ubTrace deployment, following the organization/project/version structure:
```
mkdir -p input/mycompany/myproject/v1
cp -r _build/ubtrace/* input/mycompany/myproject/v1/
```
Run the builder to process the input and generate the output data:
```
docker compose run --rm ubtrace-builder
```
Restart the API server to load the new data:
```
docker compose restart ubtrace-api
```

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:

Create subdirectories in input/ for each project, following the organization/project/version structure:

input/
  MyCompany/
    ProjectA/
      v1/
        source/
          conf.py
          index.rst
    ProjectB/
      v1/
        source/
          conf.py
          index.rst

Run the builder to process all projects:

docker compose run --rm ubtrace-builder

Restart the API server:
```
docker compose restart ubtrace-api
```

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