What is ubCode?¶

ubCode is a Rust-powered engine that deeply understands your Sphinx-Needs project. It parses your reStructuredText files, indexes every need object and its relationships, and gives you real-time feedback — all without running a full Sphinx build.

What problem does it solve?¶

Sphinx-Needs turns a Docs-as-Code approach into a full Engineering-as-Code solution: requirements, specifications, test cases, and other traceable items live right alongside your documentation source files. That is powerful, but Sphinx builds can take minutes on large projects. You write a new requirement, fix a link, or rename an ID — then wait for the build to tell you whether anything broke.

ubCode removes that wait. Its Rust core indexes thousands of files and needs in milliseconds, so diagnostics, link resolution, and traceability data update as you type. You get the full analytical power of Sphinx-Needs with the responsiveness of a modern language server.

Three ways to use it¶

ubCode is not just a VS Code extension. The same engine is available through three interfaces, so you can pick what fits your workflow:

💻 VS Code extension: Install the ubCode extension for live diagnostics, previews, navigation, auto-completion, and graph views — right in your editor. See Installation for details.
⌨ ubc CLI: A standalone binary that exposes the same engine on the command line. Run linting, build the needs index, diff two project revisions, or integrate checks into CI/CD pipelines. See Introduction for details.
🤖 MCP server: A Model Context Protocol server that gives AI assistants deep, structured access to your project’s requirements graph. See Model Context Protocol (MCP) server for details.

All three share a single Rust core and the same ubproject.toml configuration, so results are consistent regardless of how you interact with the engine.

How it relates to Sphinx and Sphinx-Needs¶

ubCode is a complement to Sphinx and Sphinx-Needs, not a replacement.

Sphinx remains your documentation build system — it turns RST into HTML, PDF, and other formats.
Sphinx-Needs remains your requirements-management extension — it defines need types, links, filters, and visualizations.
ubCode re-implements the analysis side of that pipeline in Rust for speed. It reads the same RST source files and the same need definitions, but it does so in milliseconds instead of minutes.

Because ubCode does not execute Python, it relies on a declarative ubproject.toml configuration file rather than the Python-based conf.py. Starting from Sphinx-Needs 4.1, you can share configuration between both via the needs_from_toml option — see Coming from Sphinx-Needs for migration guidance.

Note

ubCode does not run Sphinx or any user Python code. It only reads RST files and known directives/roles. Custom Sphinx extensions that do not modify primary Sphinx-Needs data can still be used alongside ubCode.

Source code tracing with Codelinks¶

Beyond RST documentation, ubCode can trace into your source code. Codelinks lets you embed traceability markers directly in code comments — one-line need definitions, need-ID references, or full RST blocks — and ubCode’s Rust engine picks them up in real time.

This means requirements can live where the code is, and the .. src-trace:: directive brings them back into your documentation automatically. Configure it through the [codelinks] section of your ubproject.toml.

Architecture at a glance¶

┌─────────────────────────────────────────────┐
│              Rust core engine                │
│  (parsing · indexing · diagnostics · query)  │
└──────┬──────────────┬──────────────┬─────────┘
       │              │              │
 Python bindings   Standalone    MCP server
    (PyO3)          binary
       │              │              │
┌──────┴──────┐  ┌───┴───┐   ┌─────┴──────┐
│ VS Code ext │  │ ubc   │   │ AI assist  │
│ (LSP)       │  │ CLI   │   │ (Copilot,  │
│             │  │       │   │  etc.)     │
└─────────────┘  └───────┘   └────────────┘

The Rust engine handles all the heavy lifting: parsing RST, resolving need links, running lint checks, evaluating queries, and scanning source code for traceability markers. Python bindings (via PyO3) connect it to the VS Code extension’s language server, while the ubc binary and MCP server call into the same Rust crates directly.

Design trade-offs¶

To achieve real-time performance, ubCode makes deliberate trade-offs:

No Python execution — ubCode cannot run conf.py or custom Sphinx extensions. All configuration must be expressed declaratively in ubproject.toml.
Known directive/role set — ubCode understands a large set of Sphinx and Sphinx-Needs directives and roles, but directives added by third-party extensions need to be declared in the configuration.
Focus on primary data — ubCode indexes the primary traceability data (need objects, links, statuses, tags, and fields). Rendering-side features such as complex Sphinx-Needs visualizations are gradually being added.

These trade-offs are intentional and continuously minimized. See the Roadmap for upcoming improvements and Supported toolchain for the current feature coverage.