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

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

Feature: Ex/Importing needs FEATURE_2

tags: introduction links outgoing: SPEC_1 links incoming: TEMPL_SPEC, TEMPL_POST_SPEC, extend_test_001

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

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

Ecosystem

In the last years additional information and extensions have been created, which are based or related to Sphinx-Needs:

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.

Sphinx-Needs.com

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.

Technical docs

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.

Technical docs

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.

Technical docs

Further Sphinx extensions

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:

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.

Technical docs

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

Technical docs

One more thing …

The sphinx-needs logo was designed by j4p4n.

Content

• Installation
  • Using poetry
  • Using pip
  • Using sources
  • Activation
  • PlantUML support
  • Using Docker
• Directives
  • need/ req (or any other defined need type)
  • needbar
  • needlist
  • needtable
  • needflow
  • needsequence
  • needgantt
  • needextract
  • needpie
  • needimport
  • needservice
  • needextend
  • needfilter
• Roles
  • need
  • need_outgoing
  • need_incoming
  • need_part / np
  • need_count
  • need_func
• Configuration
  • Activation
  • Incremental build support
  • Options
  • Removed options
• Builders
  • needs
• API
  • Configuration
  • Need
  • Exceptions

• Filtering needs
  • Filter options
  • Filter string
  • Filter code
  • Filter function
• Dynamic functions
  • Example
  • Built-in functions
  • Develop own functions
• Services
  • GitHub services
  • Configuration
  • Multiple service instances
  • Own services
• Layouts & Styles
  • Layouts
  • Styles
  • HTML output
  • Grids
• Examples
  • Different need layouts and styles
  • Referencing and filtering needs
• Performance & Profiling
  • Test series
  • Parallel execution
  • Used rst template
  • Profiling
  • Measurements

• Support
  • Professional Support
  • Convince your team
• Contributing
  • Bugs, Features and PRs
  • Installing Dependencies
  • List make targets
  • Build docs
  • Running Tests
  • Linting & Formatting
  • Running Test Matrix
  • Running Commands
  • Maintainers
  • Contributors
  • Publishing a new release
• Changelog & License
  • License
  • 0.7.10
  • 0.7.9
  • 0.7.8
  • 0.7.7
  • 0.7.6
  • 0.7.5
  • 0.7.4
  • 0.7.3
  • 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