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

# needflow

Added in version 0.2.0.

needflow creates a flowchart of filtered needs.

If you provide an argument, we use it as caption for the generated image.

Example 1

    .. needflow:: My first needflow
       :filter: is_need
       :tags: flow_example
       :link_types: tests, blocks
       :show_link_names:
       :config: lefttoright

My first needflow

Added in version 2.2.0: You can now also set all or individual `needflow` directives to use the Graphviz engine for rendering the graph, which can speed up the rendering process for large amount of graphs.

See the needs_flow_engine configuration option and the directive engine option for more information.

Using Graphviz engine

My first needflow

## Dependencies

### plantuml

`needflow`, with the default `plantuml` engine, uses PlantUML and the Sphinx-extension sphinxcontrib-plantuml for generating the flows.

Both must be available and correctly configured to work.

Please read install plantuml for a step-by-step installation explanation.

### graphviz

`needflow`, with the `graphviz` engine uses the Graphviz dot executable for rendering the flowchart, and the built-in `sphinx.ext.graphviz` extension from Sphinx.

See https://graphviz.org/download/ for how to install Graphviz, and `sphinx.ext.graphviz` for configuration options. In particular, you may want to set the `graphviz_output_format` configuration option in your `conf.py`.

## Options

Note

needflow supports the full filtering possibilities of Sphinx-Needs. Please see Filtering needs for more information.

### engine

Added in version 2.3.0.

You can set the engine to use for rendering the flowchart, to either `plantuml` (default) or `graphviz`.

### alt

Added in version 2.3.0.

Set the `alt` option to a string to add an alternative text to the generated image.

### root_id

Added in version 2.2.0.

To select a root need for the flowchart and its connected needs, you can use the `:root_id:` option. This takes the id of the need you want to use as the root, and then traverses the tree of connected needs, to create an initial selection of needs to show in the flowchart.

Connections are limited by the link types you have defined in the `:link_types:` option, or all link types if not defined. The direction of connections can be set with the `:root_direction:` option: `both` (default), `incoming` or `outgoing`.

If `:root_depth:` is set, only needs with a distance of `root_depth` to the root need are shown.

Other need filters are applied on this initial selection of connected needs.

Example 2

    .. needflow::
       :root_id: spec_flow_002
       :root_direction: incoming
       :link_types: tests, blocks
       :show_link_names:

    .. needflow::
       :root_id: spec_flow_002
       :root_direction: outgoing
       :link_types: tests, blocks
       :show_link_names:

    .. needflow::
       :root_id: spec_flow_002
       :root_direction: outgoing
       :root_depth: 1
       :link_types: tests, blocks
       :show_link_names:

Using Graphviz engine

### show_filters

Adds information of used filters below generated flowchart.

Example 3

    .. needflow::
       :tags: flow_example
       :show_filters:

Used filter: tags(flow_example)

Using Graphviz engine

Used filter: tags(flow_example)

### show_legend

Adds a legend below generated flowchart. The legends contains all defined need-types and their configured color for flowcharts.

Example 4

    .. needflow::
       :tags: flow_example
       :show_legend:

Using Graphviz engine

### show_link_names

Added in version 0.3.11.

Adds the link type name beside connections.

You can configure it globally by setting needs_flow_show_links in conf.py. Setup data can be found in test case document tests/doc_test/doc_extra_links.

Example 5

    .. needflow::
       :tags: flow_example
       :show_link_names:

Using Graphviz engine

### link_types

Added in version 0.3.11.

Defines the link types to show in the needflow. Must contain a comma separated list of link type names.

    .. needflow::
       :link_types: links,blocks

By default, we show all link_types.

An identical link can show up twice in the generated needflow, if the `copy` option of a specific link type was set to `True`.

In this case, the link_type “link” also contains the copies of the specified link_type and therefore there will be two identical connections in the needflow. You can avoid this by not setting “links” in the `link_type` option.

You can set this option globally via the configuration option needs_flow_link_types.

See also needs_extra_links for more details about specific link types.

Example 6

    .. req:: A requirement
       :id: req_flow_001
       :tags: flow_example

    .. spec:: A specification
       :id: spec_flow_001
       :blocks: req_flow_001
       :tags: flow_example

       :need_part:`(subspec_1)A testable part of the specification`

       :need_part:`(subspec_2)Another testable part of the specification`

       .. spec:: A child specification
          :id: spec_flow_003
          :blocks: req_flow_001
          :tags: flow_example

    .. spec:: Another specification
       :id: spec_flow_002
       :links: req_flow_001
       :blocks: spec_flow_001
       :tags: flow_example

    .. test:: A test case
       :id: test_flow_001
       :tests: spec_flow_002, spec_flow_001.subspec_1, spec_flow_001.subspec_2
       :tags: flow_example

    .. needflow::
       :tags: flow_example
       :link_types: tests, blocks
       :show_link_names:

Requirement: A requirement req_flow_001
tags: flow_example links incoming: spec_flow_001, spec_flow_003, spec_flow_002 is blocked by: spec_flow_001, spec_flow_003

Specification: A specification spec_flow_001
tags: flow_example links outgoing: req_flow_001 links incoming: spec_flow_002, test_flow_001 child needs: spec_flow_003 blocks: req_flow_001 is blocked by: spec_flow_002 is tested by: test_flow_001

A testable part of the specification subspec_1

Another testable part of the specification subspec_2

Specification: A child specification spec_flow_003
tags: flow_example links outgoing: req_flow_001 parent needs: spec_flow_001 blocks: req_flow_001

Specification: Another specification spec_flow_002
tags: flow_example links outgoing: req_flow_001, spec_flow_001 links incoming: test_flow_001 blocks: spec_flow_001 is tested by: test_flow_001

Test Case: A test case test_flow_001
tags: flow_example links outgoing: spec_flow_002, spec_flow_001.subspec_1, spec_flow_001.subspec_2 tests: spec_flow_002, spec_flow_001.subspec_1, spec_flow_001.subspec_2

Using Graphviz engine

### config

Added in version 0.5.2.

You can specify a configuration using the `:config:` option but you should set the needs_flow_configs configuration parameter in conf.py, when using the `plantuml` engine, or the needs_graphviz_styles configuration, when using the `graphviz` engine.

Example 7

    .. needflow::
       :filter: is_need
       :tags: flow_example
       :types: spec
       :link_types: tests, blocks
       :show_link_names:
       :config: monochrome

You can apply multiple configurations together by separating them via `,` symbol.

Example 8

    .. needflow::
       :filter: is_need
       :tags: flow_example
       :types: spec
       :link_types: tests, blocks
       :show_link_names:
       :config: monochrome,lefttoright,handwritten

Using Graphviz engine

Sphinx-Needs provides some necessary configurations already.

For `needs_flow_configs` they are:

config name | description
--- | ---
mixing | Allows mixing of different PlantUML diagram types (e.g. Class and Deploy diagrams)
monochrome | Changes all colors to monochrome colors
handwritten | All lines look like they were handwritten (squiggly)
lefttoright | Direction of boxes is left to right
toptobottom | Direction of boxes is top to bottom (PlantUML default value)
transparent | Transparent background
tne | Tomorrow night eighties theme. Look here for example.
cplant | Cplant theme. Read this for example.

For `needs_graphviz_styles` they are:

config name | description
--- | ---
default | Default style used when `config` is not set
lefttoright | Direction of boxes is left to right
toptobottom | Direction of boxes is top to bottom (default value)
transparent | Transparent background

### scale

Added in version 0.5.3.

You can set a scale factor for the final flow chart using the `scale` option.

`:scale: 50` will set width and height to `50%` of the original image size.

We also support the numbers between `1` and `300`.

Example 9

    .. needflow::
       :filter: is_need
       :tags: flow_example
       :link_types: tests, blocks
       :scale: 50

### highlight

Added in version 0.5.3.

The `:highlight:` option takes a single Filter string as a value and sets the border for each need of the needflow to red if the need also passes the filter string.

Example 10

    .. needflow::
       :tags: flow_example
       :link_types: tests, blocks
       :highlight: id in ['spec_flow_002', 'subspec_2'] or type == 'req'

Using Graphviz engine

### border_color

Added in version 3.0.0.

The `:border_color:` allows for setting per need border colors, based on the need data. The value should be written with the variant syntax, and each return value should be a hex (RGB) color.

Example 11

    .. needflow:: Engineering plan to develop a car
       :tags: flow_example
       :link_types: tests, blocks
       :border_color:
          [type == 'req']:FF0000,
          [type == 'spec']:0000FF,
          [type == 'test']:00FF00

Engineering plan to develop a car

Using Graphviz engine

Engineering plan to develop a car

### align

You can set the alignment for the PlantUML image using the `align` option. Allowed values are: `left`, `center`, `right`

Example 12

    .. needflow::
       :filter: is_need and type == 'spec'
       :tags: flow_example
       :align: center

Using Graphviz engine

### debug

Added in version 0.5.2.

If you set the `:debug:`, we add a debug-output of the generated PlantUML code after the generated image.

Helpful to identify reasons why a PlantUML build may have thrown errors.

Example 13

    .. needflow::
       :filter: is_need
       :tags: flow_example
       :link_types: tests, blocks
       :config: lefttoright, handwritten
       :debug:

    @startuml

    ' Config

    left to right direction
    skinparam handwritten true

    ' Nodes definition

    node "<size:12>Requirement</size>\n**A requirement**\n<size:10>req_flow_001</size>" as req_flow_001 [[../directives/needflow.html#req_flow_001]] #BFD8D2
    node "<size:12>Specification</size>\n**A specification**\n<size:10>spec_flow_001</size>" as spec_flow_001 [[../directives/needflow.html#spec_flow_001]] #FEDCD2{
    'parts:
    'child needs:
    node "<size:12>Specification</size>\n**A child**\n**specification**\n<size:10>spec_flow_003</size>" as spec_flow_003 [[../directives/needflow.html#spec_flow_003]] #FEDCD2
    }
    node "<size:12>Specification</size>\n**Another**\n**specification**\n<size:10>spec_flow_002</size>" as spec_flow_002 [[../directives/needflow.html#spec_flow_002]] #FEDCD2
    node "<size:12>Test Case</size>\n**A test case**\n<size:10>test_flow_001</size>" as test_flow_001 [[../directives/needflow.html#test_flow_001]] #DCB239

    ' Connection definition

    spec_flow_001 -[#AA0000]-o req_flow_001
    spec_flow_003 -[#AA0000]-o req_flow_001
    spec_flow_002 -[#AA0000]-o spec_flow_001
    test_flow_001 -[#00AA00]-> spec_flow_002

    @enduml

Using Graphviz engine

     1digraph needflow {
     2compound=true;
     3graph [
     4  rankdir="LR";
     5  bgcolor="transparent";
     6]
     7node [
     8  margin="0.21,0.11";
     9]
    10edge [
    11  minlen="2";
    12]
    13
    14// node definitions
    15"req_flow_001" [label=<<font point-size="12">Requirement</font><br align="left"/><b>A requirement</b><br align="left"/><font point-size="10">req_flow_001</font><br align="left"/>>, tooltip="req_flow_001", href="needflow.html#req_flow_001", target="_top", shape="box3d", style="filled", fillcolor="#BFD8D2"];
    16subgraph "cluster_spec_flow_001" {
    17  label=<<font point-size="12">Specification</font><br align="center"/><b>A specification</b><br align="center"/><font point-size="10">spec_flow_001</font><br align="center"/>>;
    18  tooltip="spec_flow_001";
    19  href="needflow.html#spec_flow_001";
    20  target="_top";
    21  shape="node";
    22  style=filled;
    23  fillcolor="#FEDCD2";
    24
    25  "spec_flow_001" [style=invis, width=0, height=0, label=""];
    26  // parts:
    27  // child needs:
    28  "spec_flow_003" [label=<<font point-size="12">Specification</font><br align="left"/><b>A child<br align="left"/>specification</b><br align="left"/><font point-size="10">spec_flow_003</font><br align="left"/>>, tooltip="spec_flow_003", href="needflow.html#spec_flow_003", target="_top", shape="box3d", style="filled", fillcolor="#FEDCD2"];
    29
    30};
    31"spec_flow_002" [label=<<font point-size="12">Specification</font><br align="left"/><b>Another<br align="left"/>specification</b><br align="left"/><font point-size="10">spec_flow_002</font><br align="left"/>>, tooltip="spec_flow_002", href="needflow.html#spec_flow_002", target="_top", shape="box3d", style="filled", fillcolor="#FEDCD2"];
    32"test_flow_001" [label=<<font point-size="12">Test Case</font><br align="left"/><b>A test case</b><br align="left"/><font point-size="10">test_flow_001</font><br align="left"/>>, tooltip="test_flow_001", href="needflow.html#test_flow_001", target="_top", shape="box3d", style="filled", fillcolor="#DCB239"];
    33
    34// edge definitions
    35"spec_flow_001" -> "req_flow_001" [color="#AA0000", arrowhead=odiamond, ltail="cluster_spec_flow_001"];
    36"spec_flow_003" -> "req_flow_001" [color="#AA0000", arrowhead=odiamond];
    37"spec_flow_002" -> "spec_flow_001" [color="#AA0000", arrowhead=odiamond, lhead="cluster_spec_flow_001"];
    38"test_flow_001" -> "spec_flow_002" [color="#00AA00", arrowhead=vee];
    39}

### common filters

- status

- tags

- types

- filter