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

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

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

Needs can be easily filtered and presented in 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

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**Developed for**\n**safe process**\n**executions**\n<size:10>FEATURE_7</size>" as FEATURE_7 [[../index.html#FEATURE_7]] #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

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

For complex data chains between needs, Dynamic functions can be used to load and set changeable data automatically during documentation generation phase.

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.

Feature: API for other extensions FEATURE_6 _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_7 _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

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 additional information and extensions have been created, which are based or related to Sphinx-Needs:

img-top

Sphinx-Needs.com

Webpage to present most important Sphinx-Needs functions and related extensions.

Good entrypoint to understand the benefits and to get an idea about the complete ecosystem of Sphinx-Needs.

img-top

Sphinx-Needs

Base extension, which provides all of its functionality under the MIT license for free.

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

img-top

Sphinx-Needs Enterprise

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

Provides scripts to baseline data and make CI usage easier.

img-top

Sphinx-Test-Reports

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

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

During the work with Sphinx-Needs in bigger, company internal projects, other Sphinx extensions have been created to support the work in teams of the automotive industry:

img-top

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

Sources like git repositories, jinja based files or symlinks are supported.

img-top

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

One more thing …

The sphinx-needs logo was designed by j4p4n.

Content