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

My sequence chart

Show the needs used in the above example

User: Mr. A USER_A

style: blue_border links outgoing: ACT_ISSUE links incoming: ACT_INFORM

Action: Creates issue ACT_ISSUE

style: yellow_border links outgoing: USER_B links incoming: USER_A

User: Ms. B USER_B

style: blue_border links outgoing: ACT_ANALYSIS, ACT_SOLUTION links incoming: ACT_ISSUE, ACT_ANALYSIS

Action: Analysis issue ACT_ANALYSIS

style: yellow_border links outgoing: USER_B links incoming: USER_B

Action: Provides solution ACT_SOLUTION

style: yellow_border links outgoing: USER_C links incoming: USER_B

User: Expert C USER_C

style: blue_border links outgoing: ACT_REVIEW, ACT_INFORM links incoming: ACT_SOLUTION, ACT_REVIEW

Action: Reviews solution ACT_REVIEW

style: yellow_border links outgoing: USER_C links incoming: USER_C

Action: Informs reporter ACT_INFORM

style: yellow_border links outgoing: USER_A links incoming: USER_C

User: Office Dog USER_D

style: blue_border triggers: ACT_BARKS triggered by: ACT_BARKS

Action: Barks for support ACT_BARKS

style: yellow_border triggers: USER_D triggered by: USER_D

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

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

My filtered sequence chart