Coming from Sphinx-Needs¶

Configuration¶

Sphinx uses a Python file called conf.py to configure a project.

ubCode needs access to the project configuration to learn about directives, roles, and other settings for the language server to gain its insights. Importing the configuration from Python is not possible as it may depend on custom imports or require a certain Python version. It is also time consuming.

To solve this problem, ubCode uses a declarative configuration file called ubproject.toml.

Starting from version 4.1 Sphinx-Needs supports the configuration option needs_from_toml. It allows reading all Sphinx-Needs related configuration from a TOML file.

To easily migrate all Sphinx-Needs configuration data, you can set up a custom Sphinx extension that writes the current configuration to a TOML file:

Create a new python file script.py into the folder that contains conf.py with content:

# /// script
# dependencies = ["tomli-w"]
# ///
# uv run script.py
import conf, tomli_w

need_attributes = {}
for attribute in dir(conf):
    if attribute.startswith("needs_"):
        # skip any attributes that have non-serializable values
        need_attributes[attribute[6:]] = getattr(conf, attribute)
# add this text to ubproject.toml
print(tomli_w.dumps({"needs": need_attributes}))

You might need to add import dependencies of conf.py to the script.

Run it with uv run script.py.

It looks for all variables starting with needs_ and print them to the console.
Put the output to ubproject.toml.
Configure Sphinx-Needs to read this file by adding the following to your conf.py:
```
needs_from_toml = 'ubproject.toml'
```
Remove all Sphinx-Needs specific configuration from your conf.py.

For more details, please read about the ubproject.toml file.

Mindset¶

Sphinx-Needs is a powerful extension for Sphinx that allows you to define requirements, specifications and other structured information in your documentation. It provides a lot of features to manage and visualize these requirements.

Sphinx-Needs already creates huge value because it turns a Docs-as-Code approach into a whole Engineering-as-Code solution. Sphinx builds can take some time to finish. This is ok in CI contexts, however on local developer machines, it can be a bit slow.

ubCode is designed to overcome this limitation. The stated goal of ubCode is to get real-time insights into all the traceability data Sphinx-Needs manages and generates. This enables you to work with the data in a more interactive way, and to get immediate feedback on the traceability of your project. This is especially useful when you are working on large projects with many requirements.

To build the internal ubCode data index in a performance expected from a language server, ubCode cannot rely on calling Sphinx or Python to get the data. Instead, it comes with its own parser and indexer that is optimized for speed and memory usage. It’s written in Rust in large parts.

Sphinx is popular for its flexibility and extensibility. Users can add local extensions and also Sphinx-Needs offers a Python API that can be used to add data to the internal structure. ubCode does not execute any user Python code, it only reads RST files with a large set of known directives and roles and it also supports imported/external needs.

This means trade-offs have to be made to achieve the performance and real-time capabilities. ubCode strives to reduce the trace-offs to the least possible amount. Custom Sphinx extensions that do not modify primary Sphinx-Needs data can still be used.

ubCode does not support all features of Sphinx-Needs yet, but it supports the most important ones.