Downloads License Supported versions https://readthedocs.org/projects/sphinx-needs/badge/?version=latest GitHub CI Action status PyPI Package latest release black code style Sphinx-Needs Logo

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.

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 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.

Specification: Content of each need SPEC_1 _images/arrow-right-circle.svg
status: open
tags: introduction, awesome, nice

Each need contains:

  • a title (required)

  • an unique id (optional) - gets generated based on the title if not given

  • a description (optional) - supports rst and sphinx extensions fully

  • 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

We can easily filter needs and present them as lists, tables, diagrams, and pie charts.

Table example

ID

Title

Outgoing

FEATURE_1

Filtering needs

FEATURE_2

Ex/Importing needs

FEATURE_3

Connect to external services

FEATURE_4

Automated data handling

FEATURE_5

Customizing everything

FEATURE_6

API for other extensions

FEATURE_7

Supports PlantUML for reusable Architecture elements

FEATURE_8

Developed for safe process executions

REQ_1

What is a need

SPEC_1

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

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

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.

make html   # HTML output
make needs  # needs.json containing all data
Feature: Connect to external services FEATURE_3 _images/arrow-right-circle.svg
tags: introduction
links outgoing: SPEC_1
links incoming: extend_test_001

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.

Feature: Automated data handling FEATURE_4 _images/arrow-right-circle.svg
tags: introduction
links outgoing: SPEC_1

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
tags: introduction
links outgoing: SPEC_1

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.

Feature: API for other extensions FEATURE_6 _images/arrow-right-circle.svg
tags: introduction
links outgoing: SPEC_1

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.

Feature: Supports PlantUML for reusable Architecture elements FEATURE_7 _images/arrow-right-circle.svg
tags: introduction
links outgoing: SPEC_1

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.

Feature: Developed for safe process executions FEATURE_8 _images/arrow-right-circle.svg
tags: introduction
links outgoing: SPEC_1

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

Requirement: My first requirement req_001 _images/arrow-right-circle.svg
tags: main_example
links incoming: S_503A1

This need is a requirement, and it includes a title, an ID, a tag and this text as a description.

Specification: Spec for a requirement S_503A1 _images/arrow-right-circle.svg
status: done
tags: important, main_example
links outgoing: req_001

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 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

A more powerful table (based on DataTables):

ID

Title

Status

Outgoing

req_001

My first requirement

S_503A1

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:

card-img-top

Sphinx-Needs.com

The website presents the essential Sphinx-Needs functions and related extensions.

Also, it is a good entry point to understand the benefits and get an idea about the complete ecosystem of Sphinx-Needs.

card-img-top

Sphinx-Needs

Create, update, link, filter and present need objects like Requirements, Specifications, Bugs and many more.

The base extension provides all of its functionality under the MIT license for free.

card-img-top

Sphinx-Needs Enterprise

Synchronize Sphinx-Needs data with external, company internal systems like CodeBeamer, Jira or Azure Boards.

Provides scripts to baseline data and makes CI usage easier.

card-img-top

Sphinx-Test-Reports

Extension to import test results from XML files as need objects.

Created need objects can be filtered and linked to specification objects.

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:

card-img-top

Sphinx Collections

Extension to collect or generate files from different sources and include them in the Sphinx source folder.

It supports sources like Git repositories, Jinja based files or symlinks.

card-img-top

Sphinx Bazel

Provides a Bazel domain in Sphinx documentation and allows the automated import of Bazel files and their documentation.

One more thing …

j4p4n designed the Sphinx-Needs logo.