Warning
The project was renamed from sphinxcontrib-needs to sphinx-needs. This affects all URLs and package names.
Requirements, Bugs, Test cases, … inside Sphinx¶
Sphinx-Needs is an extension for the Python based documentation framework Sphinx, which you can simply extend by different extensions to fulfill nearly any requirement of a software development team.
Sphinx-Needs allows the definition, linking and filtering of need-objects, which are by default:
requirements
specifications
implementations
test cases.
You can easily customize the list above via configuration. For instance, you can customize the need objects to support bugs, user stories or features.
A need is a generic object which can become anything you want for your Sphinx documentation: a requirement, a test case, a user story, a bug, an employee, a product, or anything else. But regardless of whatever you choose it to be and how many of them you require, we handle each need object the same way. |
Each need contains:
|
We can easily filter needs and present them as lists, tables, diagrams, and pie charts. |
Table example
ID |
Title |
Outgoing |
|---|---|---|
Filtering needs |
||
Ex/Importing needs |
||
Connect to external services |
||
Automated data handling |
||
Customizing everything |
||
API for other extensions |
||
Supports PlantUML for reusable Architecture elements |
||
Developed for safe process executions |
||
What is a need |
||
Content of each need |
Diagram example
![@startuml
' Nodes definition
node "<size:12>Requirement</size>\n**What is a need**\n<size:10>REQ_1</size>" as REQ_1 [[../index.html#REQ_1]] #BFD8D2
node "<size:12>Specification</size>\n**Content of each**\n**need**\n<size:10>SPEC_1</size>" as SPEC_1 [[../index.html#SPEC_1]] #FEDCD2
node "<size:12>Feature</size>\n**Filtering needs**\n<size:10>FEATURE_1</size>" as FEATURE_1 [[../index.html#FEATURE_1]] #FFCC00
node "<size:12>Feature</size>\n**Ex/Importing**\n**needs**\n<size:10>FEATURE_2</size>" as FEATURE_2 [[../index.html#FEATURE_2]] #FFCC00
node "<size:12>Feature</size>\n**Connect to**\n**external**\n**services**\n<size:10>FEATURE_3</size>" as FEATURE_3 [[../index.html#FEATURE_3]] #FFCC00
node "<size:12>Feature</size>\n**Automated data**\n**handling**\n<size:10>FEATURE_4</size>" as FEATURE_4 [[../index.html#FEATURE_4]] #FFCC00
node "<size:12>Feature</size>\n**Customizing**\n**everything**\n<size:10>FEATURE_5</size>" as FEATURE_5 [[../index.html#FEATURE_5]] #FFCC00
node "<size:12>Feature</size>\n**API for other**\n**extensions**\n<size:10>FEATURE_6</size>" as FEATURE_6 [[../index.html#FEATURE_6]] #FFCC00
node "<size:12>Feature</size>\n**Supports**\n**PlantUML for**\n**reusable**\n**Architecture**\n**elements**\n<size:10>FEATURE_7</size>" as FEATURE_7 [[../index.html#FEATURE_7]] #FFCC00
node "<size:12>Feature</size>\n**Developed for**\n**safe process**\n**executions**\n<size:10>FEATURE_8</size>" as FEATURE_8 [[../index.html#FEATURE_8]] #FFCC00
' Connection definition
SPEC_1 --> REQ_1
FEATURE_1 --> SPEC_1
FEATURE_2 --> SPEC_1
FEATURE_3 --> SPEC_1
FEATURE_4 --> SPEC_1
FEATURE_5 --> SPEC_1
FEATURE_6 --> SPEC_1
FEATURE_7 --> SPEC_1
FEATURE_8 --> SPEC_1
@enduml](_images/plantuml-bfdfdaa7349c57360ced242f1882a2b623460735.svg)
For external synchronization (e.g. with JIRA, a spreadsheet,…), the needs builder can help export all created needs to a single JSON file. Also, there is support for importing needs from external files, which you can do by using the needimport directive. |
Sphinx-Needs can request issues and other data from external services like GitHub. Embed tickets, requirements and other external information from specific services into your documentation by using Services. |
To handle complex data chains between needs, you can use Dynamic functions to load and set changeable data automatically during the documentation generation phase. |
Customizing everything
|
Feature
|
||||
Sphinx-Needs allows customizing needs-types, needs-options, colors, layouts, IDs, checks, …. The pages Configuration and Layouts & Styles contains instructions on how to adopt Sphinx-Needs for your processes and workflows. |
|||||
The API allows other Sphinx-extensions to build specific solutions around and with Sphinx-Needs. For instance, Sphinx-Test-Reports create needs from test results and make them searchable and linkable to other need-types. |
Sphinx-Needs allows to create specific objects for architecture elements, which can be reused and recombined in different flows and also higher architecture elements. Based on PlantUML. Take a look into the needuml directive to get an impression how powerful this mechanism is. |
Sphinx-Needs allows you to define the exact way of using and configuring needs objects. Use needs_statuses, needs_tags or needs_warnings to check for configurations not allowed, e.g. wrong status names. Or force the usage of specifically defined need-ids by setting needs_id_required and needs_id_regex. See Configuration for more options to get a Sphinx documentation valid with ISO 26262, DO-178B/C or any other safety standard. |
Example¶
For more complex examples, please visit Examples.
Input¶
**Some data**
.. req:: My first requirement
:id: req_001
:tags: main_example
This need is a requirement, and it includes a title, an ID, a tag and this text as a description.
.. spec:: Spec for a requirement
:links: req_001
:status: done
:tags: important; main_example
:collapse: false
We didn't set the **ID** option here, so **Sphinx-Needs** will generate one for us.
But we have set a **link** to our previous requirement and have set the **status** option.
Also, we have enabled **collapse** to false to show all meta-data directly under the title.
**Some text**
Wohooo, we have created :need:`req_001`,
which is linked by :need_incoming:`req_001`.
**Some filters**
Simple list:
.. needlist::
:tags: main_example
Simple table:
.. needtable::
:tags: main_example
:style: table
A more powerful table
(based on `DataTables <https://datatables.net/>`_):
.. needtable::
:tags: main_example
:style: datatables
Result¶
Some data
This need is a requirement, and it includes a title, an ID, a tag and this text as a description. |
We didn’t set the But we have set a link to our previous requirement and have set the status option. Also, we have enabled collapse to false to show all meta-data directly under the title. |
Some text
Wohooo, we have created My first requirement (req_001), which is linked by S_503A1.
Some filters
Simple list:
Simple table:
A more powerful table (based on DataTables):
ID |
Title |
Status |
Outgoing |
|---|---|---|---|
My first requirement |
|||
Spec for a requirement |
done |
Ecosystem¶
In the last years, we have created additional information and extensions, which are based on or related to Sphinx-Needs:
Other Sphinx extensions¶
During the use of Sphinx-Needs in popular companies’ internal projects, we have created other Sphinx extensions to support the work of teams in the automotive industry:
One more thing …¶
j4p4n designed the Sphinx-Needs logo.