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.toml lists both parsers, [parse.parsers.rst] and [parse.parsers.md].

  • Changes: ubCode runs no Python, so it reads no conf.py setting and resolves none of the functions your needs_functions registers (the built-in dynamic functions do resolve). A directive from an extension it does not know is a placeholder reported as block.directive_unknown, which fails ubc build html and ubc build pdf by 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, as build.directive_unhandled (build.pdf_directive_unhandled in 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:

  1. Write the script

    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

    Run it with uv run script.py.

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

  3. Paste the output

    Put the output to ubproject.toml.

  4. 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'
    
  5. 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.