Coming from Sphinx-Needs¶
Your Sphinx build does not have to change:
ubCode does not run Sphinx or your conf.py, it reads the same source files directly.
What it needs is a ubproject.toml
with your Sphinx-Needs configuration,
plus the Sphinx settings your sources rely on, such as rst_prolog, extlinks and intersphinx.
To keep one copy of the Sphinx-Needs part, add needs_from_toml to conf.py (Sphinx-Needs 4.1 or later),
and Sphinx-Needs reads that same file (Configuration below shows how).
Keeps working: your reStructuredText sources, unedited, and the Sphinx-Needs directives, roles and configuration listed under Supported toolchain. MyST Markdown is read too, once
ubproject.tomllists both parsers,[parse.parsers.rst]and[parse.parsers.md].Changes: ubCode runs no Python, so it reads no
conf.pysetting and resolves none of the functions yourneeds_functionsregisters (the built-in dynamic functions do resolve). A directive from an extension it does not know is a placeholder reported asblock.directive_unknown, which failsubc build htmlandubc build pdfby default. Declaring it under [parse] extend_directives checks its argument and content and completes its options in the editor, but it stays a placeholder and still fails the builds, asbuild.directive_unhandled(build.pdf_directive_unhandledin a PDF).Rendered differently, or not at all: Unsupported syntax lists what ubCode does not render, with what to write instead, and Differences from a Sphinx build lists where ubCode’s preview and builds differ.
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:
Write the script
Create a new python file
script.pyinto the folder that containsconf.pywith 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
Run it with
uv run script.py.It looks for all variables starting with
needs_and prints them to the console.Paste the output
Put the output to
ubproject.toml.Point Sphinx-Needs at the file
Configure Sphinx-Needs to read this file by adding the following to your
conf.py:needs_from_toml = 'ubproject.toml'
Remove the old configuration
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?. The live preview renders your content as you type; the Authoring section is a reference for exactly what it renders, and Differences from a Sphinx build lists where it deliberately differs from a full Sphinx build.
Source code tracing with Codelinks¶
If you have been using needimport or custom scripts to link source code artifacts to needs, consider switching to ubCode’s built-in source code tracing.
Codelinks lets you embed traceability markers directly in code comments —
one-line need definitions, need-ID references, or full RST blocks —
and ubCode picks them up in real time.
The .. src-trace:: directive then brings those traced needs
into your documentation automatically.
This replaces the workflow of exporting data from code,
importing it via needimport, and rebuilding
with a live, always-up-to-date traceability link.
See the codelinks guide for a walkthrough, or Codelinks (source code tracing) for the full configuration reference.