Using multi line options (attributes) of needs elements easily

[PhilipPartsch]

I'm currently thinking about an easy opportunity to set multi line options (attributes) of a needs element. Additionally I would want to set meta data of the attribute, too.

Attributes of an (needs attribute) E.g.

• if it is multi line
• if it is plantuml code

What are your thoughts about?

[PhilipPartsch]

My idea for uml content: I want to have a need element e.g. component. In needflow and needuml, the refered need should show up as defined in conf.py style.

But if I refer the defined attribute (e.g. i could have two attributes: structure - "for a class diagramm" and activity- "for an activity diagramm"), I would get the defined uml code from the refered attribute. So I could reuse the uml code even more defined in the current scope (structure modelling or behaviour modelling).

[danwos]

Mhh I like the idea of having two or more plantuml-based representations of a need-object.

With the implementation of https://github.com/useblocks/sphinxcontrib-needs/pull/610, the PlantUML code of the first found needuml gets stored as option in the need: need['diagram'].

If this is set, the jinja-function uml() is using this information inside needuml.

Maybe we could let the user decide, how the needuml-code inside the content area of a need gets stored in the same need.

Example:

.. req:: my requirement
   :id: REQ_001
   :status: open

   This is a component requirement.
   
   .. needuml:: 

      card "interface" as int
     ...

  .. needuml::
     :need_option: sequence

      int --> component: Hello there!

In the above case the following gets stored under:

• need['diagram']: The first needuml, as it is the first one and no need_option is set
• need['sequence'] The content of the second needuml.

Following rules must be used for needuml in content:

• The first needuml gets stored under diagram if no need_option is used
• Other needuml directs are not stored, as long as no need_option is set (for sure they are rentered in the need itself).
• Maybe there should be hard coded / configurable names for need_option, so that it is used a common way in all docs.

Other tasks:

• uml() function of needuml should get a parameter, which allows to define the need-option which has PPlantUML code stored.

What do you think?

[PhilipPartsch]

What I want to solve with needattribute is to have an easy way to author multi line content. The title of the directive is the name of the attribute. When I recognized that uml code is even multi line content and could be indicted as an option to the multi line content. This would make a consistent look and feel for the author. So a needuml / needflow would been used to request a rendering of a diagram with in the rst and not to define the content of an attribute.

[danwos]

Can you give me an example? It's hard for me to imagine how some rst-code would look like.

[PhilipPartsch]

For sure I can. See needattribute.rst in PR. Here is a example how it renders.

A remark, I added debug output during uml processing, so finally the source code will not be avaialbe in the end.

[PhilipPartsch]

I believe here is the right place to discuss the concept. It is always easier to talk about a solution and improve it, than only talk about a concept. And as I'm doing all development in my free time, after work and child care(mostly late at night as you can see in the commit history), I'm free to create unused prototypes :). So with draft PR #616 I tried to create a first prototype and to discuss my Ideas. I like to see how it would be printed in the end.

[PhilipPartsch]

@danwos You asked if needextend is similar to needattribute? As far as I know, it is not easy with needextend to define a multiline option for a need. Is it possible? Could we get a example? I only know this description in need. And I think, to write multiline options like this is ugly and difficult to review. So that's why I created needattribute.