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
├── ubtrace_server.toml
├── MyCompany
│   └── MyProduct
│       └── version_x
│           ├── config
│           │    └── ubproject.toml
│           ├── db
│           └── docs
└── useblocks
    └── ubtrace
        ├── 1
        │   ├── config
        │   │    └── ubproject.toml
        │   ├── db
        │   └── docs
        └── 2
            ├── config
            │    └── ubproject.toml
            ├── db
            └── docs

Each project version contains three folders:

config: Stores project-specific configs for ubTrace as ubproject.toml. See Project Options.
db: Contains a file-based database with Sphinx-Needs objects for traceability reports.
docs: Documentation output as json data.

At the root level, a general configuration file for the ubTrace server is stored: ubtrace_server.toml. See Server Options for server configuration details.

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 ubproject.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.
The output under _build/ubtrace can be used directly with ubTrace. Map this folder into the Docker container by updating your docker-compose.yml:
```
ubtrace:
  volumes:
    - ./my_docs/_build/ubtrace/:/home/useblocks/app/docs/ubtrace/
```
Note

The syntax is LOCAL_PATH:SERVER_PATH. SERVER_PATH must be /home/useblocks/app/docs/ubtrace. LOCAL_PATH can be any folder on your machine, but it must contain the structure generated by the ubTrace builder.
Restart ubTrace:
```
docker compose up
```

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 a shared folder outside your Sphinx projects, for example all_my_projects.
Copy the project-specific artifacts from each project’s _build/ubtrace/ into all_my_projects.
Make sure all_my_projects contains the needed server configuration file: ubtrace_server.toml

Update your docker-compose.yml:

ubtrace:
  volumes:
    - ./all_my_projects/:/home/useblocks/app/docs/ubtrace/

Restart ubTrace:
```
docker compose up
```

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