needs_extra_options only for selected need types

[marcin-nowacki]

Currently I can only add needs_extra_options to all needs. I would like to however add certain options to certain need types. For example I can imagine following configuration file:

needs_extra_options = {
   '*': {
       #here are options for all need types
       "general_option1",
       "general_option2",
    },
   'req': {
         "option1 ",
         "option2 ",
    },
}

another possibility would be to add "private" options in the needs_types definition, for example option1 and option2 in req:

needs_types = [dict(directive="req", title="Requirement", prefix="R_", color="#BFD8D2", style="node", options=["option1", "option2"]),
               dict(directive="spec", title="Specification", prefix="S_", color="#FEDCD2", style="node"),
               dict(directive="impl", title="Implementation", prefix="I_", color="#DF744A", style="node"),
               dict(directive="test", title="Test Case", prefix="T_", color="#DCB239", style="node"),
               # Kept for backwards compatibility
               dict(directive="need", title="Need", prefix="N_", color="#9856a5", style="node")
           ]

similar approach would likely be needed to be applied to needs_extra_links and maybe this is even more important to have this possibility there where wrong options could be used for linking.

[danwos]

Thanks for the idea. 👍

The question is, what is the goal of having such a config?
For instance:

• Shall it automatically be checked during a build? I think yes, but is their an opt-in/out option?
• Shall it be checked by the used IDE during entering the rst/md code?
• Shall not allowed values be highlighted in the built documentation?

You can take this idea further by also allowing specific values only for specific options.
In the end, you end up wanting a powerful model definition for each need-type, which gets checked during build time, for instance also with a different status-flow.

Here are some already existing solutions, that make such checks possible, but with additional configs outside the need_type definition:

• Use need_warnings to define rules based on a python expression.
• Use Sphinx-Modelling to define need-models with pydantic. Allows complex validations.
• Use external tools to check the data stored in the needs.json file during a build (in the build_finished event). Some users are using a rdf/turtle based stack to do this.

I'm not sure if Sphinx-Needs should prefer a model definition in its package, or if this is something that can be introduced from outside, like the Sphinx-Modelling package does.
Sphinx-Needs follows more or less the rule Be simple by default, but make complex settings possible.

[marcin-nowacki]

we have many need types in our project, and although we have strict definition which options are to be used for which type, the users sometimes mix up the needs and use options that are not meant to be used. Of course you could make a check for each option and add a warning, but it is more work than just defining it like shown above, and the maintenance is more difficult and annoying compared to simple definition, which would be straightforward. The solution should be standard and easy, and the first proposal of my solution is I think the best, it makes you think right away about where should you define your options when you add them and prevents problems in the future.

[twodrops]

Unfortunately, the keep it simple approach scales only when Sphinx-Needs is used in small scopes. For large enterprises (> 150 need-types, > 300 need_options and need_links), this unfortunately becomes often a limitation. We have to invent other mechanisms to workaround this.

The main requirements , as I mentioned here, are

• a typed model specification, ideally python neutral and
• a possibility of specifiying constraints, ideally python neutral.

A python neutral (ideally a standard based specification), is needed in such enterprises for integration with other tools, reusability, maintaintability (esp. by visualizating the metamodel) and standardisation efforts.

In the end, this has a larger scope than Sphinx-Needs and could well be argued that it needs to be solved outside of Sphinx-Needs (as we do in our organization with RDF). It would however be nice if Sphinx-Needs could also provide some kind of a more typed dictionary specification like @marcin-nowacki proposed.

[twodrops]

Related discussion is here #601

@marcin-nowacki We have a solution at our company for this. Please contact me directly 😄

[marcin-nowacki]

ok, thank you, will get back to you when I am back from vacation next week