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
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
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
show_link_names¶
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
link_types¶
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
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
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
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
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
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
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