needflow

New 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

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

Result

@startuml ' 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: blocks spec_flow_003 -[#AA0000]-o req_flow_001: blocks spec_flow_002 -[#AA0000]-o spec_flow_001: blocks test_flow_001 -[#00AA00]-> spec_flow_002: tests @enduml

My first needflow

Dependencies

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

Options

Note

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

show_filters

Adds information of used filters below generated flowchart.

Example

.. needflow::
   :tags: main_example
   :show_filters:

Result

@startuml ' Nodes definition node "<size:12>Requirement</size>\n**My first**\n**requirement**\n<size:10>req_001</size>" as req_001 [[../index.html#req_001]] #BFD8D2 node "<size:12>Specification</size>\n**Spec for a**\n**requirement**\n<size:10>S_503A1</size>" as S_503A1 [[../index.html#S_503A1]] #FEDCD2 ' Connection definition S_503A1 --> req_001 @enduml

Used filter: tags(main_example)

show_legend

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

Example

.. needflow::
   :tags: main_example
   :show_legend:

Result

@startuml ' Nodes definition node "<size:12>Requirement</size>\n**My first**\n**requirement**\n<size:10>req_001</size>" as req_001 [[../index.html#req_001]] #BFD8D2 node "<size:12>Specification</size>\n**Spec for a**\n**requirement**\n<size:10>S_503A1</size>" as S_503A1 [[../index.html#S_503A1]] #FEDCD2 ' Connection definition S_503A1 --> req_001 ' Legend definition legend |= Color |= Type | |<back:#BFD8D2> #BFD8D2 </back>| Interface | |<back:#BFD8D2> #BFD8D2 </back>| Component | |<back:#BFD8D2> #BFD8D2 </back>| System | |<back:#BFD8D2> #BFD8D2 </back>| Requirement | |<back:#FEDCD2> #FEDCD2 </back>| Specification | |<back:#DF744A> #DF744A </back>| Implementation | |<back:#DCB239> #DCB239 </back>| Test Case | |<back:#FFCC00> #FFCC00 </back>| Feature | |<back:#777777> #777777 </back>| User | |<back:#FFCC00> #FFCC00 </back>| Action | |<back:#FF3333> #FF3333 </back>| Milestone | |<back:#cccccc> #cccccc </back>| Issue | |<back:#aaaaaa> #aaaaaa </back>| PullRequest | |<back:#888888> #888888 </back>| Commit | endlegend @enduml

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

Example

.. needflow::
   :tags: main_example
   :show_link_names:

Setup data can be found in test case document tests/doc_test/doc_extra_links

Result

@startuml ' Nodes definition node "<size:12>Requirement</size>\n**My first**\n**requirement**\n<size:10>req_001</size>" as req_001 [[../index.html#req_001]] #BFD8D2 node "<size:12>Specification</size>\n**Spec for a**\n**requirement**\n<size:10>S_503A1</size>" as S_503A1 [[../index.html#S_503A1]] #FEDCD2 ' Connection definition S_503A1 --> req_001: links outgoing @enduml

New 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

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

Result

Requirement: A requirement req_flow_001 ../_images/arrow-right-circle.svg
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 ../_images/arrow-right-circle.svg
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 ../_images/arrow-right-circle.svg
tags: flow_example
links outgoing: req_flow_001
parent needs: spec_flow_001
blocks: req_flow_001
Specification: Another specification spec_flow_002 ../_images/arrow-right-circle.svg
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

@startuml ' 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: rectangle "<size:12>Specification (part)</size>\n**A testable part**\n**of the**\n**specification**\n<size:10>spec_flow_001.**subspec_1**</size>" as spec_flow_001.subspec_1 [[../directives/needflow.html#spec_flow_001.subspec_1]] #FEDCD2 rectangle "<size:12>Specification (part)</size>\n**Another**\n**testable part**\n**of the**\n**specification**\n<size:10>spec_flow_001.**subspec_2**</size>" as spec_flow_001.subspec_2 [[../directives/needflow.html#spec_flow_001.subspec_2]] #FEDCD2 '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: blocks spec_flow_003 -[#AA0000]-o req_flow_001: blocks spec_flow_002 -[#AA0000]-o spec_flow_001: blocks test_flow_001 -[#00AA00]-> spec_flow_002: tests test_flow_001 -[dotted,#00AA00]-> spec_flow_001.subspec_1: tests\n test_flow_001 -[dotted,#00AA00]-> spec_flow_001.subspec_2: tests\n spec_flow_001.subspec_1 -[dotted,#AA0000]-o req_flow_001: blocks\n spec_flow_001.subspec_2 -[dotted,#AA0000]-o req_flow_001: blocks\n @enduml

config

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

Example

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

Result

@startuml ' Config skinparam monochrome true ' Nodes definition 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 ' Connection definition spec_flow_002 -[#AA0000]-o spec_flow_001: blocks @enduml

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

Example

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

Result

@startuml ' Config skinparam monochrome true left to right direction skinparam handwritten true ' Nodes definition 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 ' Connection definition spec_flow_002 -[#AA0000]-o spec_flow_001: blocks @enduml

Sphinx-Needs provides some necessary configurations already. 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.

scale

New 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

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

Result

@startuml ' 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

highlight

New 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

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

Result

@startuml ' 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;line:FF0000 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: rectangle "<size:12>Specification (part)</size>\n**A testable part**\n**of the**\n**specification**\n<size:10>spec_flow_001.**subspec_1**</size>" as spec_flow_001.subspec_1 [[../directives/needflow.html#spec_flow_001.subspec_1]] #FEDCD2 rectangle "<size:12>Specification (part)</size>\n**Another**\n**testable part**\n**of the**\n**specification**\n<size:10>spec_flow_001.**subspec_2**</size>" as spec_flow_001.subspec_2 [[../directives/needflow.html#spec_flow_001.subspec_2]] #FEDCD2;line:FF0000 '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;line:FF0000 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 test_flow_001 -[dotted,#00AA00]-> spec_flow_001.subspec_1 test_flow_001 -[dotted,#00AA00]-> spec_flow_001.subspec_2 spec_flow_001.subspec_1 -[dotted,#AA0000]-o req_flow_001 spec_flow_001.subspec_2 -[dotted,#AA0000]-o req_flow_001 @enduml

align

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

Example

.. needflow::
   :filter: is_need
   :tags: flow_example
   :align: center

Result

@startuml ' Nodes definition 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 ' Connection definition spec_flow_002 --> spec_flow_001 spec_flow_002 -[#AA0000]-o spec_flow_001 @enduml

debug

New 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

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

Result

@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

@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

common filters