repository·master·Indexed 43 days ago
https://github.com/useblocks/sphinx-needsA collection of Sphinx extensions for requirements management, traceability, and test reporting. The ecosystem includes sphinx-needs for core requirements, sphinx-mounts for mounting external source trees without copying, sphinx-codelinks for source-code traceability via comment markers, and sphinx-test-reports for converting JUnit, ctest, googletest, and tox-envreport results into Sphinx needs.
Sphinx-Needs is used to define, link, and filter class-like "need-objects". By default, these objects represent:
These types can be customized via configuration to support other entities like bugs or user stories. The extension also provides powerful tools for analyzing and visualizing needs through directives like needtable, needflow, and needpie.
CodeLinks is a utility designed for fast source code tracing and integration with the Sphinx-Needs ecosystem. It consists of four primary components:
Configuration is managed via a single TOML file used by both the Sphinx extension and the CLI application.
The Source Analyse module in Sphinx-CodeLinks extracts documentation-related content from source code comments. It allows developers to embed documentation directly in source code while maintaining a clean separation. It provides both CLI and API interfaces and supports generating structured JSON output for downstream processing.
Primary Extraction Modes:
Supported Languages & Comment Styles:
//, /* *///, /* */, ///##//, /* */, ///////, /* */#Note: Each analysis run can only process one comment style at a time.
sphinx-needs is a Sphinx extension designed to bring "Engineering-as-Code" to the documentation framework. It allows you to define, link, and analyze engineering objects (such as requirements, specifications, features, and test cases) directly within your Sphinx documentation.
ISO 26262 or DO-178B/C.sphinx-needs and extensive configuration options.dynamic_functions to manage complex data chains and automatically update data during the documentation generation phase.PlantUML to create reusable architecture elements that can be combined into flow diagrams.Sphinx CodeLinks is a Sphinx extension designed to discover, link, and document source code across different projects. Its core capabilities include:
Sphinx-Test-Reports is a Sphinx extension designed to display test results directly within Sphinx documentation. It is particularly useful for projects requiring human-readable documentation of test outcomes and environment configurations (e.g., for safety-critical standards like ISO 26262).
Key features include:
tox-envreport.The sphinx-needs repository is a monorepo managed as a uv workspace containing several specialized Sphinx extensions. While they are developed together to ensure compatibility, they are distributed as independent packages to manage dependencies efficiently and allow for independent versioning.
Key packages include:
sphinx-needs: The core Sphinx extension for managing requirements and specifications.sphinx-mounts: An extension for mounting external source trees into a Sphinx build without copying or symlinking.sphinx-codelinks: Provides fast source-code traceability by scanning source files for comment markers, converting them into needs, and linking documentation to exact source lines.sphinx-test-reports: Converts test results (JUnit, ctest, googletest XML, and tox-envreport JSON) into Sphinx needs. It includes a test-reports command to generate a needs.json without running a full Sphinx build.sphinx-mounts is part of the useblocks documentation tooling ecosystem. Most tools in this ecosystem use a shared ubproject.toml convention for configuration:
| Tool | Configuration Table in ubproject.toml | Purpose |
|---|---|---|
| sphinx-mounts | [[source.mounts]] | Mounts external sources in place. |
| Sphinx-Needs | [needs] | Requirements management and traceability. |
| sphinx-codelinks | [codelinks] | Bidirectional source-to-doc traceability. |
| ubCode | N/A | Language server for validation and cross-references. |
Related specialized tools:
bazel-drives-sphinx: A heavier Bazel-driven companion to sphinx-mounts.needs-config-writer: Bridges dynamic Python/Bazel configuration with the static ubproject.toml used by sphinx-mounts and ubCode.sphinx-collections: A more general alternative for assembling content (supports copy, symlink, git clone, etc.) if you need more than just in-place reading.The Sphinx-Needs API is organized into several functional modules. When building extensions or custom tools, you will interact with these core areas:
sphinx_needs.api.configuration: Handles the injection of extra configuration.sphinx_needs.api.need: The primary interface for defining and managing needs.sphinx_needs.exceptions: Contains custom exception classes for error handling within the extension.sphinx_needs.need_item: Provides data structures for individual needs, links, and parts (e.g., NeedItem, NeedLink, NeedPartItem).sphinx_needs.data: Defines data types and protocols used throughout the system (e.g., NeedsInfoType, NeedsPartType).sphinx_needs.views: Provides view objects used by filters. Warning: Do not instantiate these classes directly; they are intended to be returned by functions or injected into filters.sphinx_needs.needs_schema & sphinx_needs.schema.config: Define the schema and field types for needs, including support for literal values, links, and specific field types (String, Boolean, Integer, etc.).sphinx-mounts is a Sphinx extension designed to bridge the gap between modern build systems (like Bazel) and IDE-based Docs-as-Code workflows. It allows Sphinx to read documentation files (RST or Markdown) directly from their original filesystem locations without copying, symlinking, or staging them into the Sphinx srcdir.
ubCode) to provide live feedback (cross-reference highlighting, linting, and previews) for files that live outside the standard Sphinx source tree.variant_sources key in ubproject.toml, allowing sphinx-build to narrow its document set per variant.| Aspect | sphinx-collections | sphinx-mounts |
|---|---|---|
| Core Strategy | Generic/Driver-based: Sphinx fetches or generates content (via git, copy, jinja, etc.) and writes it to _collections/ inside srcdir. | Focused/Zero-copy: Content already exists at a known path; Sphinx reads it in place without materialization. |
| On-disk location | <srcdir>/_collections/<name>/ | Original filesystem path |
| Configuration | collections dict in conf.py | [[source.mounts]] array in ubproject.toml |
| IDE Experience | Editor sees files only after a build; contents may not be in VCS. | Editor sees original files directly via the shared ubproject.toml contract. |
| Best Fit | When Sphinx needs to pull content from heterogeneous sources (URLs, Git, templates). | When a build system already provides files and you want to avoid staging/duplication. |
Sphinx-Needs provides an open API designed for other Sphinx extensions to interact with the needs ecosystem. Developers can use this API to:
Note: While the API allows for the injection of extra configuration, it does not support the removal of existing need types to ensure the final configuration remains transparent to Sphinx project authors.