Features¶
🔍 Features
ID |
Title |
SI |
Errors |
|---|---|---|---|
Display Traceability objects content in Sphinx-Needs |
yes |
||
Generate object representation in Sphinx-Needs |
yes |
||
Apply dynamic functions for meta-data computation |
yes |
||
Export needs.json file using Sphinx-Needs |
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 |
|
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 |
|
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 |
||
Extend page content with templates in Sphinx-Needs |
yes |
||
Automatic ID generation |
yes |
||
Configuration via conf.py or an external TOML file |
no |
||
Customizable layouts for need presentation |
yes |
||
Customizable link types |
yes |
||
Customizable need options |
yes |
||
Definable need types |
yes |
||
Create a bar chart based on need statistics (needbar) |
no |
||
Modify existing needs in bulk (needextend) |
yes |
||
Render a PlantUML flow diagram of needs (needflow) |
no |
||
Import needs from an external JSON file (needimport) |
yes |
||
Create a pie chart based on need statistics (needpie) |
no |
||
Display needs in a filterable table (needtable) |
no |
||
Constraint checking to validate need relationships |
yes |
||
JSON builder to export all need data |
yes |
||
Permalink generation to specific need objects |
yes |
||
Bidirectional link tracking |
yes |
||
Dead link detection and warnings |
yes |
||
Direct linking between needs using IDs |
yes |
||
Manual ID assignment |
yes |
||
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 options that any need object can have, such as ‘author’ or ‘component’. These custom options can be displayed in tables and used for filtering. # In conf.py
needs_extra_options = ['author', 'component']
.. req:: A specific requirement
:id: R_001
:author: John Doe
:component: UI
|
Define different types of links between needs to represent various relationships. This helps to create a precise traceability model. # In conf.py
needs_extra_links = [
{
"option": "verifies",
"incoming": "verified by",
"outgoing": "verifies",
},
{
"option": "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. |
Automated Features¶
Define rules, or constraints, 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. # In conf.py
needs_constraints = {
"req_verified": {
"check_code": "len(links_back['verifies']) > 0",
"severity": "error",
"filter": "'req' in tags"
}
}
|
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
|
Generate a |