Manually setting parent_needs

[sebastiansetzer]

Manually setting parent_needs doesn't work. The setting gets overwritten by what sphinx-needs figures out to be the parent according to the nesting in the rst source.

Is this intended behaviour (parent_needs is meant to be readonly) or should it be possible to manually set parent_needs?

The use-case is defining child needs somewhere else, usually in a separate file, than where the parent is defined.
If it's not possible to use parent_needs for parent-child relationships, you'd have to define a custom "parent" option. And that would not work out of the box with .. needflow, for example.

Currently, you can use .. needextend to overwrite parent_needs. But if parent_needs is meant to be readonly, I guess you can't trust that this works in future versions of sphinx-needs.
And it doesn't work reliably even now. When it's in the same rst file as the child need, it seems to work. But when it is with the parent need, the parent_needs are not shown as outgoing links in the child.

Edit: .. needextend seems to always work. Can't reproduce the strange observation after make clean.
Edit: The change to allow setting parent_needs manually would be trivial.
Just replace one = by +=:

need_info["parent_needs"] += parent_needs

If there are no objections, I would create a PR for this. I just have to figure out how to make a test case for it.
Edit: Here's the PR: #1609

[ubmarco]

This topic has a bigger scope unfortunately:

• parent_needs (and parent_need being the text of parent_needs[0]) currently means 'nested anywhere in RST body`. It is therefore a calculated field, so overwriting this would change the semantics of that. The original source of information is the exact location of the nested need in the body of a parent need.
• parent_needs is a link field, so it can be target of need schema validation. I added a test that shows how this can be done.
• I see the concept of nesting needs in the RST body more and more problematic:
  1. When exporting data, the target formats needs to support this. When looking into ReqIF or SysMLv2, this is not the case AFAIK.
  2. For needs.json there is already an issue whether to import the root need or the nested need as it appears on the parent. Setting this manually would introduce a third option. Also the manual setting can conflict with the real nesting of items. I would like to avoid a semantic shift of the existing concept of 'parent need'.
  3. Complexity; developers and users need to understand what it means to nest a need and know about the consequences (like cannot export to other systems). More maintenance also on our end for Sphinx-Needs and ubCode.
• When reading through your request, I think you could use link relationships to express what you want. What you won't get then is needflow seeing the linked need as a child element. Maybe it makes sense to have a setting like is_containment on needs_extra_links, which means exactly one item must be linked, and the link type will show up as a containment in needflow.

Please comment whether I understood you right and what your preferred solution is. Cannot promise an implementation or a timeline, let's first see what the requirement would be.

Thanks for your PR. Unfortunately, I can also say that this will not be enough. As outlined above, the field is calculated and has a clear semantics, so overwriting it does not make sense.

[sebastiansetzer]

When reading through your request, I think you could use link relationships to express what you want.

I wondered if I should just add my own link type, with needs_extra_links. Call it parent (looks nicer than parent_needs anyway, when manually entered).

I could then hook into needs-before-post-processing to populate it from parent_needs, and this way have something that can be specified manually and by nesting.
I would then need my own layout in order to hide parent_needs, because it would look a bit ugly to have both parent_needs and parent links displayed.

It is therefore a calculated field

I'm aware of that, and I would like to keep the calculated values from nesting, just add them to the manually specified ones instead of overwriting them. That's why #1609 just turns = into +=.

I very much would like to keep the ability to quickly draft an outline with list2need, and later on, when working on the details of the need, turn it into a free-standing need, but preserve the parent/child relationship by manually specifying the parent.

Is there some reason why a calculated field can not also be specified manually? In my use-case, it would be either/or, but since it is a list anyway, it could even be both, calculated and manually specified, resulting in the union of both. And the PR does that.

Would this reason also apply to my own link type, so my plan outlined above (needs_extra_links, add parent) wouldn't work out for some reason?

Also note that today it is already possible to overwrite parent_needs with .. needextend. Should I assume that this is just by accident, and unsupported?

When exporting data, the target formats needs to support this

Does it? Why does the target format have to understand the semantics of nesting, and can't treat it as "just another link type"?

For needs.json there is already an issue

It is indeed a bit annoying to have the nested needs appear twice in the JSON, but is it really worsened by the ability to specify parent_needs manually, in which case they appear only once in the JSON?

Actually, I would prefer having the nested needs never appear in the content field of the JSON. I already have a tool consuming the JSON that has to filter them out. Simply by removing all directives it finds inside the content. Only works because right now I have no use case for other directives inside those needs. To make the tool more robust, and only remove the directives that declare nested needs, I would have to add a configuration (maybe parse needs_from_toml config files) to teach it which directives are need types.

I see the concept of nesting needs in the RST body more and more problematic

Well, I'm not suggesting to add that - it already exists, and I'm mostly happy with how it is implemented. Do you plan removing support for nesting?