Tutorial

In this tutorial, we will demonstrate the use of sphinx-needs to build up a simplified engineering plan for a car. We will create need items, link them together, visualize the relationships between them, and generate traceability reports.

Engineering plan to develop a car

Engineering plan to develop a car

Prerequisites

This tutorial assumes that you have already installed sphinx-needs, and that you have a basic understanding of how to use Sphinx and reStructuredText.

Need Lifecycle

Within a sphinx build, a primary role of sphinx-needs is to manage the lifecycle of need items:

  1. Collect: During the read phase, need items are collected from the source files and configured external sources.

  2. Resolve: After the read phase, the need items are post-processed to resolve dynamic fields and links, etc, then frozen.

  3. Analyse: During the write phase, various directives/roles are available to reference, query, and output analysis of the needs.

  4. Render: During the write phase, the need items are rendered into the output format, such as HTML or PDF.

  5. Validate: During the final phase, the need items can be validated against configured checks.

Creating need items

The first core component of sphinx-needs are need items, which you can think of as nodes in a graph.

Each item must have at least:

  • a type (which corresponds to a directive),

  • a unique identifier (that can be auto-generated)

  • a title, and

  • a description.

A need item is a generic object which can become anything you you require for your project: a requirement, a test case, a user story, a bug, an employee, a product…

sphinx-needs comes with some default types: req, spec, impl, and test, which can be used as directives:

Example 1: A basic need item

.. req:: Basic need example
    :id: basic_example

    A basic example of a need item.
Requirement: Basic need example basic_example

A basic example of a need item.

For our car though, we want to use custom types, to describe aspects of the process. This can be created in the conf.py file, using the needs_types configuration option:

needs_types = [
    {
        "directive": "tutorial-project",
        "title": "Project",
        "prefix": "P_",  # prefix for auto-generated IDs
        "style": "rectangle", # style for the type in diagrams
        "color": "#BFD8D2", # color for the type in diagrams
    }
]

There are also some optional directive fields that can be used to add additional data to the item or further style its representation:

Example 2: A custom need item

.. tutorial-project:: Our new car
    :id: T_CAR
    :tags: tutorial
    :layout: clean_l
    :image: _images/car.png
    :collapse: true

    Presenting the “TeenTrek,” an autonomous driving car tailored for teenagers without a driving license.
    Equipped with advanced AI navigation and safety protocols, it ensures effortless and secure transportation.
    The interior boasts entertainment systems, study areas, and social hubs, catering to teen preferences.
    The TeenTrek fosters independence while prioritizing safety and convenience for young passengers.
_images/car.png
Project: Our new car T_CAR
tags: tutorial
layout: clean_l
image: _images/car.png
requires: T_SAFE, T_CONNECT

Presenting the “TeenTrek,” an autonomous driving car tailored for teenagers without a driving license. Equipped with advanced AI navigation and safety protocols, it ensures effortless and secure transportation. The interior boasts entertainment systems, study areas, and social hubs, catering to teen preferences. The TeenTrek fosters independence while prioritizing safety and convenience for young passengers.

See also

For full options see the reference sections for needs_types configuration and need items directive.

To add additional fields to the directive, see the needs_extra_options and needs_global_options.

Enforcing valid need items

To enforce the usage of specifically defined need ID formats, you can configure needs_id_required and needs_id_regex.

To enforce specific values for need item options, you can configure needs_statuses, needs_tags or needs_warnings to check for disallowed values.

These will emit warnings when building the documentation if the values are not as expected.

Referring to a need item

We can refer to the needs we create in the text using the need role. By default this will display the title and ID of the need item, but we can also different fields to display, by using an explicit title and using [[field]] syntax:

Example 3: Referring to a need item

The project is described in more detail in :need:`T_CAR`.

The project is described in more detail in :need:`[[title]] <T_CAR>`.

The project is described in more detail in Our new car (T_CAR).

The project is described in more detail in Our new car.

We shall also see later how to create tables and other visualizations of multiple items.

Linking need items

Now that we know how to create individual need items, the next thing we may want to do is to link them together.

We can define custom link types in the conf.py file, using the extra links configuration option:

need_extra_links = [
  {
    "option": "tutorial_required_by",
    "incoming": "requires",  # text to describe incoming links
    "outgoing": "required by",  # text to describe outgoing links
    "style": "#00AA00",  # color for the link in diagrams
  },
]

We can now uses these links when specifying need items, notice how “back links” are automatically generated when displaying the item:

Example 4: Need items with links

.. tutorial-req:: Safety Features
   :id: T_SAFE
   :tags: tutorial
   :tutorial_required_by: T_CAR

   The car must include advanced safety features such as automatic braking, collision avoidance systems, and adaptive cruise control to ensure the safety of teenage drivers.

.. tutorial-req:: Connectivity and Entertainment
   :id: T_CONNECT
   :tags: tutorial
   :tutorial_required_by: T_CAR

   The car should be equipped with built-in Wi-Fi, Bluetooth connectivity, and compatibility with smartphone integration systems to enable seamless communication and entertainment for teenagers on the go.
Requirement: Safety Features T_SAFE
tags: tutorial
required by: T_CAR
specified by: T_RADAR, T_DIST

The car must include advanced safety features such as automatic braking, collision avoidance systems, and adaptive cruise control to ensure the safety of teenage drivers.

Requirement: Connectivity and Entertainment T_CONNECT
tags: tutorial
required by: T_CAR

The car should be equipped with built-in Wi-Fi, Bluetooth connectivity, and compatibility with smartphone integration systems to enable seamless communication and entertainment for teenagers on the go.

Lets also add some more need items to our plan:

Add Specification items

Example 5: More need items with links

.. tutorial-spec:: Implement RADAR system
   :id: T_RADAR
   :tags: tutorial
   :tutorial_specifies: T_SAFE

   The RADAR sensor software for the car must accurately detect and track surrounding objects
   within a specified range. It should employ signal processing algorithms to filter out noise
   nd interference, ensuring reliable object detection in various weather and road conditions.
   The software should integrate seamlessly with the car's control system, providing real-time
   data on detected objects to enable collision avoidance and adaptive cruise control functionalities.
   Additionally, it should adhere to industry standards for safety and reliability, with robust
   error handling mechanisms in place.


.. tutorial-spec:: Implement distant detection
   :id: T_DIST
   :tags: tutorial
   :tutorial_specifies: T_SAFE

   Software Specification for Distance Detection Algorithm.
Specification: Implement RADAR system T_RADAR
tags: tutorial
specifies: T_SAFE
tested by: T_001, T_002, T_003, T_004

The RADAR sensor software for the car must accurately detect and track surrounding objects within a specified range. It should employ signal processing algorithms to filter out noise nd interference, ensuring reliable object detection in various weather and road conditions. The software should integrate seamlessly with the car’s control system, providing real-time data on detected objects to enable collision avoidance and adaptive cruise control functionalities. Additionally, it should adhere to industry standards for safety and reliability, with robust error handling mechanisms in place.

Specification: Implement distant detection T_DIST
tags: tutorial
specifies: T_SAFE

Software Specification for Distance Detection Algorithm.

See also

For full options see the reference sections for need_extra_links configuration and need items directive.

Importing need items

Need items can also be imported from external sources, using the needimport directive, or generated from external services, using the needservice directive.

Lets import some test cases, we add an additional tag to each, to make them easier to select later on:

Example 6: Importing need items

.. needimport:: _static/tutorial_needs.json
    :tags: tutorial,tutorial_tests
    :collapse: true
Test Case: Unit test 1 T_001
status: closed
tags: tutorial, tutorial_tests
tests: T_RADAR

Test case 1

Test Case: Unit test 2 T_002
status: in progress
tags: tutorial, tutorial_tests
tests: T_RADAR

Test case 2

Test Case: Unit test 3 T_003
status: open
tags: tutorial, tutorial_tests
tests: T_RADAR

Test case 3

Test Case: Unit test 4 T_004
status: open
tags: tutorial, tutorial_tests
tests: T_RADAR

Test case 4

See also

For full options see the reference sections for needimport directive and needservice directive.

Modifying need items

In the section above, we imported some test case needs, but they are currently not linked to any other need items.

We can extend the imported need items using the needextend directive, to add additional fields to them, such as links.

The needextend directive expects a filter argument, which is used to select the need items to extend. Here we filter by the tag we set on the imported items above:

Example 7: Extending need items

.. needextend:: "tutorial_tests" in tags
    :+tutorial_tests: T_RADAR
    :status: open

.. needextend:: T_001
    :status: closed

.. needextend:: T_002
    :status: in progress

Note

The needextend does not have any visible output, but it you look at the items, they will now have the additional link and status fields.

See also

For full options see the reference sections for needextend directive.

Summarising needs

Now we have learnt about how to introduce need items into our project, it is natural to want to be able to summarise all or a sub-set of needs.

There are three directives that can be used to do this, with different output formats:

  • needlist - to display a list of need items

  • needtable - to display a table of need items

  • needflow - to display a flow diagram of need items

All of these use a common filter logic, to select a sub-set of need items to display, either by simple options, or by using a more complex expression.

In the following example we will display a list of all need items with the tag “tutorial”, sorted by ID, and showing the status of each item:

Similarly, we can display the same items in a table format:

Example 9: Simple table

.. needtable::
    :tags: tutorial
    :sort: id
    :columns: id,type,title,status
    :style: table

ID

Type

Title

Status

T_001

tutorial-test

Unit test 1

closed

T_002

tutorial-test

Unit test 2

in progress

T_003

tutorial-test

Unit test 3

open

T_004

tutorial-test

Unit test 4

open

T_CAR

tutorial-project

Our new car

T_CONNECT

tutorial-req

Connectivity and Entertainment

T_DIST

tutorial-spec

Implement distant detection

T_RADAR

tutorial-spec

Implement RADAR system

T_SAFE

tutorial-req

Safety Features

There are currently two styles for the table; a simple HTML table, or the default datatables style to add dynamic pagination, filtering and sorting, using the DataTables JS package:

Example 10: Table with dynamic features

.. needtable::
    :tags: tutorial
    :sort: id
    :columns: id,type,title,status
    :style: datatable

ID

Type

Title

Status

T_001

tutorial-test

Unit test 1

closed

T_002

tutorial-test

Unit test 2

in progress

T_003

tutorial-test

Unit test 3

open

T_004

tutorial-test

Unit test 4

open

T_CAR

tutorial-project

Our new car

T_CONNECT

tutorial-req

Connectivity and Entertainment

T_DIST

tutorial-spec

Implement distant detection

T_RADAR

tutorial-spec

Implement RADAR system

T_SAFE

tutorial-req

Safety Features

Finally, we can display a flow diagram of the need items, to also show the relationships between them:

Example 11: Flow diagram

.. needflow:: Engineering plan to develop a car
    :alt: Engineering plan to develop a car
    :root_id: T_CAR
    :config: lefttoright,tutorial
    :show_link_names:
    :border_color:
        [status == 'open']:FF0000,
        [status == 'in progress']:0000FF,
        [status == 'closed']:00FF00
Aternative use of Graphviz engine

You can also use the Graphviz engine to render the flow diagram, by setting the engine option to graphviz:

Example 12: Flow diagram with Graphviz

.. needflow:: Engineering plan to develop a car
    :engine: graphviz
    :alt: Engineering plan to develop a car
    :root_id: T_CAR
    :config: lefttoright,tutorial
    :show_link_names:
    :border_color:
        [status == 'open']:FF0000,
        [status == 'in progress']:0000FF,
        [status == 'closed']:00FF00

Engineering plan to develop a car

Analysing Metrics

As well as summarising needs, sphinx-needs provides some built-in roles and directives to analyse metrics of need items, such as the number of items in a certain status:

In the following examples we will display metrics of the test cases we imported earlier, grouped by status:

Example 13: Count of need items

- Open: :need_count:`'tutorial_tests' in tags and status == 'open'`
- In Progress: :need_count:`'tutorial_tests' in tags and status == 'in progress'`
- Closed: :need_count:`'tutorial_tests' in tags and status == 'closed'`
  • Open: 2

  • In Progress: 1

  • Closed: 1

Example 14: Pie chart of metric

.. needpie:: Test Status
   :labels: Open, In progress, Closed
   :legend:

   'tutorial_tests' in tags and status == 'open'
   'tutorial_tests' in tags and status == 'in progress'
   'tutorial_tests' in tags and status == 'closed'
_images/need_pie_679b5.svg

Example 15: Bar chart of metric

.. needbar:: Test Status
   :horizontal:
   :xlabels: FROM_DATA
   :ylabels: FROM_DATA
   :legend:

   Status,      Tests
   Open,        'tutorial_tests' in tags and status == 'open'
   In Progress, 'tutorial_tests' in tags and status == 'in progress'
   Closed,      'tutorial_tests' in tags and status == 'closed'
Test Status

Next Steps

Now that you have seen how to create need items, link them together, and analyse metrics, you can explore the full range of options available in sphinx-needs by reading the rest of the documentation.

For a more complex project example, check out the sphinx-needs-demo site.

Also, see other extensions offered by useblocks which integrate with sphinx-needs to provide additional functionality.