Features¶
🔍 Features
ID |
Title |
SI |
Faults |
|---|---|---|---|
Display Traceability objects content in Sphinx-Needs |
yes |
||
Generate object representation in Sphinx-Needs |
yes |
||
Apply dynamic functions for meta-data computation |
yes |
ER_SN_DYN_NO_EXEC; ER_SN_DYN_INVALID2; ER_SN_DYN_WRONG_CALC; ER_SN_DYN_NO_VALUE |
|
Export needs.json file using Sphinx-Needs |
yes |
ER_SN_JSON_MIS; ER_SN_JSON_COR; ER_SN_JSON_LINKS_COR; ER_SN_JSON_CONTENT_COR |
|
Link conditions exported to needs.json |
yes |
||
Establish links between Traceability objects in Sphinx-Needs |
yes |
ER_SN_LINKS_NO_BACK; ER_SN_LINKS_NO_TARGET; ER_SN_LINKS_NO_EXT; ER_SN_LINKS_EXT_COR; ER_SN_LINKS_MISSING |
|
Conditional link evaluation (NeedLink, parse_conditions) |
yes |
ER_SN_LINK_COND_PARSE; ER_SN_LINK_COND_EVAL_WRONG; ER_SN_LINK_COND_HIDES_SAFE; ER_SN_LINK_COND_NOT_PARSED |
|
Read Traceability objects in Sphinx-Needs |
yes |
ER_SN_SYN_ER; ER_SN_JSON_NOT_FOUND; ER_SN_JSON_CORRUPTED; ER_SN_SER_AUTH; ER_SN_DATA_INVALID; ER_SN_CODE_ERR; ER_SN_JSON_FILTER; ER_SN_SER_DOWN; ER_SN_SER_INVALID |
|
Declarative schema validation of needs |
yes |
ER_SN_SCHEMA_DISABLED; ER_SN_SCHEMA_INVALID; ER_SN_SCHEMA_SELECT_WRONG; ER_SN_SCHEMA_NOT_REPORTED; ER_SN_SCHEMA_WRONG_SEVERITY; ER_SN_SCHEMA_NETWORK_MISS |
|
Assign meta-data to Traceability objects in Sphinx-Needs |
yes |
ER_SN_DYN_INVALID; ER_SN_DYN_WRONG; ER_SN_META_INVALID; ER_SN_META_NOT_COMPLIANT |
|
Enhance Need content using templates in Sphinx-Needs |
yes |
ER_SN_TEMPLATE_NEED_FILE_NOT_FOUND; ER_SN_TEMPLATE_NEED_FILE_INVALID; ER_SN_TEMPLATE_NEED_FILE_SYNTAX |
|
Extend page content with templates in Sphinx-Needs |
yes |
ER_SN_TEMPLATE_FILE_NOT_FOUND; ER_SN_TEMPLATE_FILE_INVALID; ER_SN_TEMPLATE_FILE_SYNTAX |
|
Typed need fields with JSON-Schema validation |
yes |
ER_SN_TYPED_FIELD_TYPE_MISS; ER_SN_TYPED_FIELD_ENUM_MISS; ER_SN_TYPED_FIELD_RANGE_MISS |
|
Typed link schemas (cardinality and targeting) |
yes |
||
Automatic ID generation |
yes |
ER_SN_ID_GENERATION_FAILED; ER_SN_ID_ALREADY_EXISTS; ER_SN_ID_FORMAT_INVALID; ER_SN_ID_LENGTH_INVALID |
|
Configuration via conf.py or an external TOML file |
no |
||
Customizable layouts for need presentation |
yes |
ER_SN_LAYOUT_INCORRECT_RENDERING; ER_SN_LAYOUT_MISSING_INFO; ER_SN_LAYOUT_INCORRECT_INFO |
|
Customizable link types |
yes |
||
Customizable need fields |
yes |
ER_SN_INVALID_OPTION; ER_SN_INVALID_OPTION_VALUE; ER_SN_OPTION_NOT_ALLOWED |
|
Definable need types |
yes |
||
Create a bar chart based on need statistics (needbar) |
no |
||
Modify existing needs in bulk (needextend) |
yes |
ER_SN_EXTEND_NOT_COMPLETED; ER_SN_EXTEND_FAIL_SILENTLY; ER_SN_EXTEND_NOT_VALID |
|
Render a PlantUML flow diagram of needs (needflow) |
no |
||
Import needs from an external JSON file (needimport) |
yes |
ER_SN_IMPORT_NOT_COMPLETED; ER_SN_IMPORT_NOT_VALID; ER_SN_IMPORT_NOT_ACCESSIBLE |
|
Create a pie chart based on need statistics (needpie) |
no |
||
Display needs in a filterable table (needtable) |
no |
||
Legacy constraint checking (needs_constraints) |
yes |
ER_SN_CONSTRAINT_NOT_CHECKED; ER_SN_CONSTRAINT_FAIL_SILENTLY; ER_SN_CONSTRAINT_WRONG_DATA; ER_SN_CONSTRAINT_INCOMPLETE_DATA; ER_SN_CONSTRAINT_INVALID_DATA |
|
JSON builder to export all need data |
yes |
ER_SN_EXPORT_JSON_FAIL_SILENTLY; ER_SN_EXPORT_JSON_NOT_VALID; ER_SN_EXPORT_JSON_CORRUPTED |
|
Permalink generation to specific need objects |
yes |
ER_SN_PERMALINK_FAIL_SILENTLY; ER_SN_PERMALINK_NOT_VALID; ER_SN_PERMALINK_NON_EXISTING; ER_SN_PERMALINK_WRONG_NEED |
|
Bidirectional link tracking |
yes |
||
Dead link detection and warnings |
yes |
ER_SN_DEAD_LINK_NOT_DETECTED; ER_SN_DEAD_LINK_FALSE_POSITIVE |
|
Direct linking between needs using IDs |
yes |
||
Manual ID assignment |
yes |
ER_SN_MANUAL_ID_EXISTS; ER_SN_MANUAL_ID_FORMAT_INVALID; ER_SN_MANUAL_ID_LENGTH_INVALID |
|
In-content need parts for granular references |
yes |
||
Need status enforcement |
yes |
||
Tagging support |
yes |
||
Unique ID enforcement and checks |
yes |
Read Traceability objects from rst/md files into the internal storage. |
|
|
|
Dynamic Content¶
|
|
|
Core Need Object¶
Allows the definition of custom need types beyond the built-in ones. Each type gets its own directive, title, and color for easy identification in diagrams. # In conf.py
needs_types = [
dict(directive="req", title="Requirement", prefix="R_", color="#BFD8D2"),
dict(directive="spec", title="Specification", prefix="S_", color="#FEDCD2"),
dict(directive="test", title,"Test Case", prefix="T_", color="#DCFED2"),
]
|
Define extra fields that any need object can have, such as The legacy list-style # In ubproject.toml
[needs.fields.author]
description = "Author of the need"
schema.type = "string"
[needs.fields.component]
description = "Logical sub-system the need belongs to"
schema.type = "string"
schema.enum = ["UI", "Backend", "Database"]
.. req:: A specific requirement
:id: R_001
:author: John Doe
:component: UI
|
Define different types of links between needs to represent various relationships. This is the foundation of a precise traceability model. The legacy # In ubproject.toml
[needs.links.verifies]
incoming = "verified by"
outgoing = "verifies"
schema.minItems = 1 # every need using :verifies: must link at least one target
[needs.links.implements]
incoming = "implemented by"
outgoing = "implements"
|
Sphinx-Needs can automatically generate a unique ID for any need that does not have one. The format of the ID can be configured using a prefix and a specific length. .. req:: This requirement will get an ID automatically.
:tags: auto_id
|
Allows for setting a specific, human-readable ID for a need. This is useful for referencing important requirements easily. .. req:: A requirement with a specific ID
:id: R_IMPORTANT_FEATURE
|
You can define a list of allowed statuses for needs. If a need uses a status that is not on the list, Sphinx will raise a warning during the build. # In conf.py
needs_statuses = [
('open', 'Is still open'),
('in_progress', 'Work in progress'),
('closed', 'Is closed'),
('rejected', 'Will not be implemented'),
]
|
Assign one or more tags to a need for categorization and filtering. Tags help in organizing needs and creating specific views or reports. .. spec:: A specification for the login system
:id: S_LOGIN
:tags: ui, security
|
Create references to specific sentences or parts inside a need’s content. This allows for very precise linking and traceability. .. req:: User Authentication
:id: R_AUTH
The user must be able to log in via a username and password.
The password must be stored securely. :np:`secure_storage`
.. test:: Test secure password storage
:id: T_SECURE_STORAGE
:links: R_AUTH.secure_storage
|
Sphinx-Needs automatically checks if all manually set IDs are unique across the project. The build will fail if a duplicate ID is found, ensuring data consistency.
|
Directives for Creating & Displaying Needs¶
Renders a table of needs based on specified filters. The table columns can be customized to show different need options like status or outgoing links. .. needtable::
:tags: ui
:status: open
:columns: id, title, status, links
|
Generates a flowchart that visualizes the relationships between filtered needs. This is excellent for showing process flows or dependencies. .. needflow::
:tags: login_flow
:show_legend:
|
Generates a pie chart from need data, for instance, to show the distribution of statuses. This provides a quick visual summary of the project’s state. .. needpie:: Requirements Status
:content: status
:legend:
|
Generates a bar chart to visualize need data. This is useful for comparing counts across different categories, such as components. .. needbar:: Needs per Component
:x_option: component
:x_labels: UI, Backend, Database
|
Import need objects from an external .. needimport:: ../../shared/output/needs.json
|
Modifies multiple needs at once based on a filter. You can add tags, change the status, or set any other option for all filtered needs. .. needextend:: status == 'in_progress'
:add_tags: sprint_5
|
Linking and Traceability¶
Create links between needs by referencing their unique IDs in link options. This forms the basis of all traceability in Sphinx-Needs. .. spec:: Defines how the login button works.
:id: S_LOGIN_BUTTON
.. req:: The login button must be blue.
:id: R_LOGIN_COLOR
:links: S_LOGIN_BUTTON
|
When you link from need A to need B, Sphinx-Needs automatically knows about the incoming link on need B. This allows for full, bidirectional traceability without extra work. |
The Sphinx build will issue a warning if a need links to an ID that does not exist. This helps to maintain the integrity of the traceability data.
|
Introduced with Sphinx-Needs 8.0, a link target can carry an
inline filter expression
( A link type opts in via [needs.links.verifies]
incoming = "verified by"
outgoing = "verifies"
parse_conditions = true
.. test:: Integration test for login feature
:id: T_LOGIN
:verifies: FE_LOGIN[status=="released"]
|
Automated Features¶
Warning
Define rules about your need data that are checked during the build. For example, you can enforce that every requirement must be linked to a test case. # Legacy form in conf.py (avoid for new projects)
needs_constraints = {
"req_verified": {
"check_code": "len(links_back['verifies']) > 0",
"severity": "fault",
"filter": "'req' in tags"
}
}
|
Introduced with Sphinx-Needs 7 and hardened in 8.0, schema
validation expresses data rules declaratively using a JSON-Schema
derived format. Rules are defined once, evaluated per build, and
produce structured diagnostics that downstream tools (ubCode,
A schema object consists of three parts:
Safety-critical projects (ISO 26262, IEC 61508, EN 50716) use the
# In ubproject.toml
schema_definitions_from_json = "schemas.json"
schema_debug_active = true
{
"$defs": {
"type-feature": { "properties": { "type": { "const": "feature" } } },
"safe-feature": {
"allOf": [
{ "$ref": "#/$defs/type-feature" },
{ "properties": { "si": { "const": "yes" } },
"required": ["si"] }
]
}
},
"schemas": [
{
"id": "safe-feature-has-fault",
"severity": "violation",
"message": "A safety-impacting feature must raise at least one fault",
"select": { "$ref": "#/$defs/safe-feature" },
"validate": {
"network": {
"raises": { "contains": { "local": {} }, "minContains": 1 }
}
}
}
]
}
|
Each custom field declared via This is the type-safe successor to the untyped string list form of
[needs.fields.asil]
description = "Automotive Safety Integrity Level (ISO 26262)"
schema.type = "string"
schema.enum = ["QM", "A", "B", "C", "D"]
[needs.fields.efforts]
description = "FTE days"
schema.type = "integer"
schema.minimum = 0
schema.maximum = 100
|
[needs.links.avoids]
incoming = "avoided by"
outgoing = "avoids"
schema.minItems = 1
|
Configuration & Customization¶
All Sphinx-Needs options can be configured in the main |
Change the visual presentation of needs by defining custom layouts. You can reorder options, use grids, and change how information is displayed. # In conf.py
needs_layouts = {
'my_layout': {
'grid': 'simple_side_right',
'layout': {
'side': ['id', 'status', 'tags', 'links']
}
}
}
|
Exporting & Reporting¶
Export all need objects and their relationships into a structured sphinx-build -b needs . _build
|
Added in Sphinx-Needs 8.0, [needs]
build_json = true
json_include_link_conditions = true
|
Generate a
|