Sphinx-Needs allows the definition, linking and filtering of need-objects, which are by default:
This list can be easily customized via configuration (for instance to support bugs or user stories).
A need is a generic object, which can become everything you want for your sphinx documentation: A requirement, a test case, a user story, a bug, an employee, a product or anything else.
But whatever you chose it shall be and how many of them you need, each need is handled the same way.
Each need contains:
Needs can be easily filtered and presented in lists, tables and diagrams.
For external synchronization (e.g. with JIRA, a spreadsheet, …) the builder needs is available to export all created needs to a single json file. And also importing needs from external files is supported by using needimport.
For more complex examples, please visit Examples.
**Some data**
.. req:: My first requirement
:id: req_001
:tags: main_example
This is an awesome requirement and it includes a nice title,
a given id, a tag and this text as description.
.. spec:: Spec for a requirement
:links: req_001
:status: done
:tags: important; main_example
:collapse: false
We haven't set an **ID** here, so sphinx-needs
will generated one for us.
But we have **set a link** to our first requirement and
also a *status* is given.
We also have set **collapse** to false, so that all
meta-data is shown 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
Some data
This is an awesome requirement and it includes a nice title, a given id, a tag and this text as description.
We haven’t set an ID here, so sphinxcontrib-needs will generated one for us.
But we have set a link to our first requirement and also a status is given.
We also have set collapse to false, so that all meta-data is shown 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:
| ID | Title | Status | Outgoing |
|---|---|---|---|
| S_503A1 | → Spec for a requirement | done | req_001 |
| req_001 | → My first requirement |
A more powerful table (based on DataTables):
| ID | Title | Status | Outgoing |
|---|---|---|---|
| S_503A1 | → Spec for a requirement | done | req_001 |
| req_001 | → My first requirement |
This sphinx extension is based on the needs of a software development team inside a german automotive company.
The project team was searching for a small and practical way of managing requirements and more to fulfill the parameters of the ISO 26262 standard for safety critical software.
Sphinx-Needs is part of a software bundle, which was designed to support the development of ISO 26262 compliant software. Other tools are: tox-envreport.
