Skip to content
Back to top
View this page
Edit this page

# 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

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.

| 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 needs_extra_options, and to set default values see 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:

Example 8: Simple list

    .. needlist::
        :tags: tutorial
        :sort_by: id
        :show_status:

T_001: Unit test 1 (closed)
T_002: Unit test 2 (in progress)
T_003: Unit test 3 (open)
T_004: Unit test 4 (open)
T_CAR: Our new car
T_CONNECT: Connectivity and Entertainment
T_DIST: Implement distant detection
T_RADAR: Implement RADAR system
T_SAFE: Safety Features

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

Engineering plan to develop a car

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:

- need_count role - to display the count of need items

- needpie directive - to display a pie chart of need items

- needbar directive - to display a bar chart of need items

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'

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'

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