Supported toolchain¶

ubCode and ubc were started as high-performance companion apps to efficiently develop and navigate Sphinx and Sphinx-Needs projects.

To achieve this, there are some focus areas:

Understand RST as docutils does, so it is 100% standards compliant
Understand what Sphinx adds on top, like directives, roles, domains and configuration
Support Sphinx-Needs specific directives, roles and configurations

The main goal is to ingest 100% of the primary data that Sphinx and Sphinx-Needs manage. Once that picture is complete, ubCode can provide a variety of features such as real-time indexing, previews, language server navigation, linting, formatting, schema validation, visualisations, MCP capabilities and much more.

A secondary goal is to improve the preview rendering so it becomes closer to how Sphinx renders HTML, but with outstanding performance. This means understanding more rendering-side features such as image embedding, Sphinx-Needs visualisations, rendering of certain directives and roles, etc.

This document describes which features of Sphinx and Sphinx-Needs are supported. If you stick to the features documented here, you can expect full support in ubCode and ubc. This will also have a positive impact on the qualification efforts of the overall toolchain at your organisation.

We will prioritise support for features that are widely used and requested by our users.

Configuration¶

ubCode and ubc require a declarative configuration style with TOML and JSON to fully understand Sphinx-Needs projects. Rationale:

Accessible outside of Python execution context (e.g., from Rust)
Reduces configuration complexity since the Sphinx configuration for large projects tends to become a whole software project on its own: many nested modules, 3rd party dependencies, long import time, dynamic code, etc.
Cacheable and fast-to-read configuration
Clear final state of configuration

Any configuration outside of this cannot be supported since ubCode and ubc do not execute any user Python code. There are efficient ways to deal with this by migrating your configuration or keeping the configuration in sync with what Sphinx/Sphinx-Needs would see at runtime. The new extension needs-config-writer might be worth a look.

Included features¶

Configuration¶

Directives¶

Roles¶

Upcoming features¶

Schema validation and related configuration options:
- schema key of needs_extra_options
- schema key of needs_extra_links
- needs_schema_definitions
- needs_schema_definitions_from_json
A new form of dynamic functions that works for both Sphinx-Needs and ubCode/ubc. These functions will be limited in what they can do but will cover many use cases. More details will follow once this feature is designed. A reduced Python language subset such as Starlark looks promising.
Ingestion of other data sources:
- sphinx-test-reports
- sphinx-codelinks
- Architecture data sources (concept work ongoing)

Excluded¶

Configuration¶

Dynamic conf.py configuration for Sphinx and Sphinx-Needs is not supported; see Configuration above.

Many of the configurations below are purely representational and do not impact the core data model of needs. More of these configurations will be supported in the future to improve the preview rendering.