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
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:
show_filters¶
Adds information of used filters below generated flowchart.
Example 3
.. needflow::
:tags: flow_example
:show_filters:
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:
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:
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:
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
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 |
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'
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
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
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}