License Supported versions https://readthedocs.org/projects/sphinxcontrib-needs/badge/?version=latest Travis-CI Build Status PyPI Package latest release

Requirements, Bugs, Test cases, … inside Sphinx

_images/needs_logo_big.png

Sphinx-Needs allows the definition, linking and filtering of need-objects, which are by default:

  • requirements
  • specifications
  • implementations
  • test cases.

This list can be easily customized via configuration (for instance to support bugs or user stories).

What is a need?

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:

  • a title (required)
  • an unique id (optional. Gets calculated based on title if not given)
  • a description, which supports fully rst and sphinx extensions (optional)
  • a status (optional)
  • several tags (optional)
  • several links to other needs (optional)

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.

Example

For more complex examples, please visit Examples.

Input

**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
   :collpase: 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

Result

Some data

Requirement: My first requirement req_001
tags: main_example
links incoming: S_503A1
links outgoing: None

This is an awesome requirement and it includes a nice title, a given id, a tag and this text as description.

Specification: Spec for a requirement S_503A1
status: done
tags: important main_example
links incoming: None
links outgoing: req_001

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
req_001 My first requirement  
S_503A1 Spec for a requirement done req_001

A more powerful table (based on DataTables):

ID Title Status Outgoing
req_001 My first requirement  
S_503A1 Spec for a requirement done req_001

Motivation

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.

One more thing …

The sphinx-needs logo was designed by j4p4n.