Support contents in needextend

[twodrops]

needextend currently supports add/append/removal of needs_extra_options and needs_extra_links. How about allowing to extend the contents part?

.. needextend:: SW_REQ_001
   :+derives: SYS_REQ_001

   This is extended content

needextend contents could be configured as pre, post or overwrite.

This allows to import just the meta-information as needs from external tools and then add textual content in rST.

Is this feasible?

[danwos]

Maybe it is doable on doctree-level, if the needextend-content can only be used to add (pre or post) or replace need-content (as you have written). Then we could render the rst in the needextend-directive, when this directive gets read. And later we do some direct doctree-manipulations, where we add or replace the needextend-content-node to/with the need-content-node. After that, we delete the needextend-node from the doctree.

So yes, it sounds doable :)

[PhilipPartsch]

Hi, I want to bring my 2 cent in. In the concept we have to think how to interact with templates (they do support pre, post and change already - so how to merge it?) and needref (so all versions have to be changed).

[danwos]

Not sure what you mean by "merge it".

Templates work differently currently. As they get added to the content before the rst/md-content is rendered by Sphinx. This rendering is happening very early, during reading the current need-directive.

needextend comes very late into this game, normally after all rendering is already done.

I'm not sure how we could change the current template behavior and especially what the benefits are.

@PhilipPartsch Do you have an example for me?

[PhilipPartsch]

With my input, I want to request a definition how the different methodologies to change needs lead to a final generated output.

I believe following is what an author wants:

• specify content and need attributes
• change the content and need attributes with needextend
• define output with templates to set use case specific rendering

I believe easy to implement:

• specify content and need attributes
• define output with templates to set use case specific rendering
• change the content and need attributes with needextend (not be updated in above templates)

[PhilipPartsch]

Another request I would assign to this feature. As it is possible to change the content of a need later, it shall be possible to set a warning if this happens for elements there this is not allowed. Use case: it is difficult to know which is the final output by only reviewing the definition of the need. So if someone has the use case to know all changes it should be possible to get informed about changes. This is in my opinion interacting with request #685.

[danwos]

Agree, a check would be good.

Currently, manipulations get also stored and needs are filterable based on them: https://sphinx-needs.readthedocs.io/en/latest/directives/needextend.html#monitoring-modifications

But this counter is not based on specific options or the content. Maybe a feature request to extend this mechanism would be helpful.

[twodrops]

Slightly offtopic, but good point.

But this counter is not based on specific options or the content. Maybe a feature request to extend this mechanism would be helpful.

Separate modification counters or a possibility to filter counters based on modification source (options, links or contents) would be good. We have a need_warning in our project currently to make sure that the same need is not modified with needextend more than once.

"needextend_invalid_usage": "(modifications > 1)"

Else, as the file loading order is decided by Sphinx, the last needextend will win, leading to unexpected results.