needsequence¶
Added in version 0.5.5.
needsequence adds a sequence-chart to your documentation.
Example 1
.. needsequence:: My sequence chart
:start: USER_A, USER_D
:link_types: links, triggers
Show the needs used in the above example
Sequence diagrams supports special needs-combinations, in which one type represents some kind of a participant
and another, linked need is representing the message.
Examples for this relationship are: Sender-Receiver communication , Role-Activity processes or Tool-Artifact relations.
needsequence needs at least one start-need, defined by its id in the :start: option.
The first need represents the participant. The next, linked need(s) is representing the message.
Needs linked from a message are interpreted as participant again and so on.
So the linking must be really clean to get nice, meaningful sequence diagrams out of it.
The used need-type is unimportant.
Participant-Message flow¶
The above, linked example gets interpreted for needsequence as follows:
Options¶
Some further options are accepted only for ubCode compatibility, and are otherwise ignored.
start¶
The :start: option takes a comma separated list of need ids and uses it as the starting point for
further examination of sequence data.
First need of :start: gets painted first. The need includes all related messages and other participants.
After the first need, we take the next need id from the :start: option.
And if it was not already part of the prior examination, we handle it the same way, otherwise, we ignore it.
link_types¶
:link_types: option takes a comma separated list of link type names followed during examination.
Because of that, we ignore other link_types and all participants or messages accessible by the ignored link_types.
Default: links
filter¶
You can use the :filter: option to filter participants.
We ignore all participants that does not fulfill the filter_string.
See Filter string for more information.
Default: None (no active filtering)
You can use this function to filter out a specific participant.
As an example, we use the same needsequence from the beginning, but without USER_C / Expert:
Example 2
.. needsequence:: My filtered sequence chart
:start: USER_A, USER_D
:link_types: links, triggers
:filter: "Expert" not in title
max_items¶
Added in version 8.4.0.
The maximum number of messages to show.
The limit counts messages, that is the arrows of the diagram, and not participants:
a message need that is linked to three receivers draws three arrows and so counts three times.
We stop the diagram once it has that many messages, and tell the reader how many messages it is hiding.
A truncated view says so in the page and emits a needs.max_items warning,
so that a build does not have to be read page by page to find it;
a project that caps deliberately can silence the warning with
suppress_warnings = ["needs.max_items"].
A participant is only drawn if it sends one of the messages that are shown.
:max_items: 0 means no limit, also for a project that sets needs_views_max_items.
Without the option, the diagram shows as many messages as that configuration allows.
Example 3
.. needsequence:: My shortened sequence chart
:start: USER_A, USER_D
:link_types: links, triggers
:max_items: 3
Showing the first 3 of 6 messages; refine the filter or set :max_items: (0 for all).