needflow

New in version 0.2.0.

needflow creates a flowchart of filtered needs.

If an argument is provided, this is taken as caption for the generated image.

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

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 PlantUML support 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.

Supported options:

show_filters

Adds information of used filters below generated flowchart.

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

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

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

@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>| Requirement |
|<back:#FEDCD2> #FEDCD2 </back>| Specification |
|<back:#DF744A> #DF744A </back>| Implementation |
|<back:#DCB239> #DCB239 </back>| Test Case |
|<back:#FFCC00> #FFCC00 </back>| Feature |
endlegend

@enduml

config

New in version 0.5.2.

Allows to specify a configuration, which must be provided by setting needs_flow_configs.

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

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

Multiple configurations can be set together by separating them via ,.

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

@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 
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 already some useful configurations:

config name description
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.

scale allows to set a scale factor for the final flow chart.

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

Numbers between 1 and 300 are supported.

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

@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 
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_002 -[#AA0000]-o spec_flow_001
test_flow_001 -[#00AA00]-> spec_flow_002

@enduml

highlight

New in version 0.5.3.

highlight takes a single Filter string as value and sets the border to red for each need of the needflow, which also passes the given filter string.

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

@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 {
 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]] #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]] #FEDCD2;line:FF0000
 }
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_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

Set align value for PlantUML image. Allowed values are: left, center, right

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

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

@enduml

debug

New in version 0.5.2.

If debug is set, a debug-output of the generated PlantUML code gets added 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:

@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 
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_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 
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_002 -[#AA0000]-o spec_flow_001
test_flow_001 -[#00AA00]-> spec_flow_002

@enduml