Extended functionality of needflow and needsequence

[Thomas-Swindells-t]

Plantuml supports nesting elements allowing parent/child relationships to be displayed. Currently needsflow supports this for displaying needparts but not for other relationship types. The ability to be able to define a link type as being a 'parent' indicator and then for the generated uml to reflect this would provide significant benefits in showing architectures and grouping requirements.

Currently needsflow treats all needs as nodes and the links are edges. Needsequence in comparison has the concept of message needs and so treats some needs as edges. Supporting being able to define link needs provides more flexibility in how models are displayed. Configuration would need to be supported to configure for each need type which fields are the source need of the link, destination of the link and title of the link.

Sometimes it is beneficial to be able to visualise a component and show (almost) all needs linked with it. Currently needsflow will either render all link_types, or you can specify a subset to display. A link_type_excluded option would allow you to include all link types except for an explicit subset. For this use case it is useful just to filter the individual needs you want to focus on, but for any other needs linked to them to also be displayed (rather than those links hidden). An autoinclude flag which adds in any needs on a dangling link simplifies writing explicit filters for this.

Needsequence is not deterministic in the order that the sequence is drawn. Add a sort_key option to allow this to be controlled, defaulting to lineno (so needs in the same file are ordered as expected).

Needsequence doesn't allow the messages to be filtered, so if you have multiple flows linking the same nodes all of them get displayed. Add a msg_filter option to support filtering of messages.

Needsequence doesn't support customization of the arrow. Add support for setting both a default arrow, and also defining a key with which to read the arrow value from the messages.

Needsequence doesn't support more advanced sequence diagram functionality such as grouping messages (alt, opt), notes, autonumbering, skinparams or dividers. Add the capability of defining a key with which to read either a prefix or postfix value from the message need. This then gets rendered before/after the message line allowing most constructs to be created.

[Thomas-Swindells-t]

I've got local code that implements all of these proposals, I hope to be able to clean it up, write test cases etc shortly.

Currently I've forked needflow to make a neednestedflow (partly as a convenience of not breaking my own docs whilst I develop it) . Currently the default behaviour on neednestedflow is to assume that needs defined within other needs should be nested (so the 'parent' link is enabled by default). This is obviously not fully backwards compatible.

The options are therefore:

1. break existing behaviour in the assumption it is a sensible default going foward
2. make a seperate neednestedflow so that the behaviour is opt in but obvious (but potentially with code duplication)
3. default it off and users have to discover the option in documentation to use it.

What would the projects preference be?

[danwos]

Wow, there are a lot of amazing ideas.

I would go with option 1, as showing nested needs as nested nodes in needflow may be the supposed behavior for most users in future. An option for needflow and conf.py to deactivate this would be good.

Please try to split your changes into serveral, standalone PRs. Would make it much easier to review. Maybe also separate issues with implementation details would be helpfull to start an early, focused discussion (important are names, default values and possible results).