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:

  1. 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.

  2. Run it with uv run script.py.

    It looks for all variables starting with needs_ and print them to the console.

  3. Put the output to ubproject.toml.

  4. Configure Sphinx-Needs to read this file by adding the following to your conf.py:

    needs_from_toml = 'ubproject.toml'

  5. Remove all Sphinx-Needs specific configuration from your conf.py.

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

Mindset

ubCode is designed to give you real-time insights into all the traceability data Sphinx-Needs manages — without waiting for a full Sphinx build. To achieve this, it comes with its own Rust-based parser and indexer that is optimized for speed and memory usage.

For a deeper look at the philosophy, architecture, and trade-offs, see What is ubCode?.