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, …) a builder “needs” is available to export all created needs to a single json file.

Example

For more complex examples, please visit Examples.

Input

**Some data**

.. req:: My first requirement
   :id: req_001
   :tags: 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; example

   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.

**Some text**

Wohooo, we have created :need:`req_001`,
which is linked by :need_incoming:`req_001`.

**A filter**

.. needfilter::
   :tags: example
   :layout: table

Result

Some data

Requirement: My first requirement (REQ_001)

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

tags: example

links incoming: S_503A1

links outgoing: None

Specification: Spec for a requirement (S_503A1)

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.

status: done

tags: important; example

links incoming: None

links outgoing: REQ_001

Some text

Wohooo, we have created My first requirement (REQ_001), which is linked by S_503A1.

A filter

Used filter: tags(example)

ID Title Type Status Links Tags
REQ_001 My first requirement Requirement   example
S_503A1 Spec for a requirement Specification done REQ_001 important; example

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.

One more thing …

This extensions also activates the usage of jinja statements inside your rst files. The statements get executed before sphinx starts handling their content.

The idea and code is coming from Eric Holscher.

It was integrated for dynamic error handling, if needed libraries like PlantUML are not available (for instance on readthedocs.io).

The sphinx-needs logo was designed by j4p4n.