https://readthedocs.org/projects/sphinxcontrib-needs/badge/?version=latest

Requirements, Bugs, Test cases, … inside Sphinx¶

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

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

status: open

tags: introduction, awesome, nice

links outgoing: REQ_1

links incoming: FEATURE_1, FEATURE_2, FEATURE_3, FEATURE_4, FEATURE_5, FEATURE_6, FEATURE_7

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

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	Connect to external services	SPEC_1
FEATURE_4	Automated data handling	SPEC_1
FEATURE_5	Customizing everything	SPEC_1
FEATURE_6	API for other extensions	SPEC_1
FEATURE_7	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**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

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: Connect to external services FEATURE_3

tags: introduction

links outgoing: SPEC_1

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

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

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

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

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

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:

req_001: My first requirement

S_503A1: Spec for a requirement

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¶

Support
- Professional Support
- Convince your team
Contributing
Changelog & License
- License
- 0.7.2
- 0.7.1
- 0.7.0
- 0.6.3
- 0.6.2
- 0.6.1
- 0.6.0
- 0.5.6
- 0.5.5
- 0.5.4
- 0.5.3
- 0.5.2
- 0.5.1
- 0.5.0
- 0.4.3
- 0.4.2
- 0.4.1
- 0.4.0
- 0.3.15
- 0.3.14
- 0.3.13
- 0.3.12
- 0.3.11
- 0.3.10
- 0.3.9
- 0.3.8
- 0.3.7
- 0.3.6
- 0.3.5
- 0.3.4
- 0.3.3
- 0.3.2
- 0.3.1
- 0.3.0
- 0.2.5
- 0.2.4
- 0.2.3
- 0.2.2
- 0.2.1
- 0.2.0
- 0.1.49
- 0.1.48
- 0.1.47
- 0.1.46
- 0.1.45
- 0.1.44
- 0.1.43
- 0.1.42
- 0.1.41
- 0.1.40
- 0.1.39
- 0.1.38
- 0.1.37
- 0.1.36
- 0.1.35
- 0.1.34
- 0.1.33
- 0.1.32
- 0.1.31
- 0.1.30
- 0.1.29
- 0.1.28
- 0.1.27
- 0.1.26
- 0.1.25
- 0.1.24
- 0.1.23
- 0.1.22
- 0.1.21
- 0.1.20
- 0.1.19
- 0.1.18