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, user stories or features.

Sphinx-Needs is an extension for the Python based documentation framework Sphinx, which can be easily extended by different extensions to fulfill nearly any requirement of a software development team.

Requirement: What is a need REQ_1 _images/arrow-right-circle.svg
tags: introduction
links incoming: SPEC_1

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.
Specification: Content of each need SPEC_1 _images/arrow-right-circle.svg
status: open
tags: introduction, awesome, nice
links outgoing: REQ_1
links incoming: FEATURE_1, FEATURE_2, FEATURE_3, FEATURE_4, FEATURE_5, FEATURE_6

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)
  • project specific options (optional, see needs_extra_options)
  • a layout (optional)
  • a style (optional)
Feature: Filtering needs FEATURE_1 _images/arrow-right-circle.svg
tags: introduction
links outgoing: SPEC_1
links incoming: TEMPL_SPEC, TEMPL_POST_SPEC
Needs can be easily filtered and presented in lists, tables, diagrams and pie charts.

Table example

ID Title Outgoing
FEATURE_1 Filtering needs SPEC_1
FEATURE_2 Ex/Importing needs SPEC_1
FEATURE_3 Automated data handling SPEC_1
FEATURE_4 Customizing everything SPEC_1
FEATURE_5 API for other extensions SPEC_1
FEATURE_6 Developed for safe process executions SPEC_1
REQ_1 What is a need
SPEC_1 Content of each need REQ_1

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**Automated data**\n**handling**\n<size:10>FEATURE_3</size>" as FEATURE_3 [[../index.html#FEATURE_3]] #FFCC00 node "<size:12>Feature</size>\n**Customizing**\n**everything**\n<size:10>FEATURE_4</size>" as FEATURE_4 [[../index.html#FEATURE_4]] #FFCC00 node "<size:12>Feature</size>\n**API for other**\n**extensions**\n<size:10>FEATURE_5</size>" as FEATURE_5 [[../index.html#FEATURE_5]] #FFCC00 node "<size:12>Feature</size>\n**Developed for**\n**safe process**\n**executions**\n<size:10>FEATURE_6</size>" as FEATURE_6 [[../index.html#FEATURE_6]] #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 @enduml

Feature: Ex/Importing needs FEATURE_2 _images/arrow-right-circle.svg
tags: introduction
links outgoing: SPEC_1
links incoming: TEMPL_SPEC, TEMPL_POST_SPEC

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.

make html   # HTML output
make needs  # needs.json containing all data
Feature: Automated data handling FEATURE_3 _images/arrow-right-circle.svg
tags: introduction
links outgoing: SPEC_1
For complex data chains between needs, Dynamic functions can be used to load and set changeable data automatically during documentation generation phase.
FEATURE_4
Customizing everything
Feature
tags: introduction
links outgoing: SPEC_1

Sphinx-needs allows to customize needs-types, needs-options, colors, layouts, ids, checks, … .

The pages Configuration and Layouts & Styles are full of possibilities to adopt Sphinx-needs for your own processes and workflows.
layout: complete
  
style: yellow
Feature: API for other extensions FEATURE_5 _images/arrow-right-circle.svg
tags: introduction
links outgoing: SPEC_1

The API allows other sphinx-extension to build specific solutions around and with Sphinx-Needs.

For instance Sphinx-Test-Reports creates needs from test results and makes them searchable and linkable to other need-types.
Feature: Developed for safe process executions FEATURE_6 _images/arrow-right-circle.svg
tags: introduction
links outgoing: SPEC_1

Sphinx-needs allows to define the exact allowed way of using and configuring needs.

Use needs_statuses, needs_tags or needs_warnings to check for not allowed configurations, e.g. wrong status names.

Or force the usage of exactly 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 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

Result

Some data

Requirement: My first requirement req_001 _images/arrow-right-circle.svg
tags: main_example
links incoming: S_503A1
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 _images/arrow-right-circle.svg
status: done
tags: important, main_example
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 in the Python environment.

Sphinx-Needs is part of a software bundle, which was designed to support the development of ISO 26262 compliant software. Other tools are: sphinx-test-reports, sphinx-collections and tox-envreport.

One more thing …

The sphinx-needs logo was designed by j4p4n.

Content