needs_model: A more complex model for sphinx-needs config.

[danwos]

Currently needs_types, needs_extra_links/options, needs_warnings are not related to each other.

But there are a lot of use cases, where e.g. only specific options for a specific need-types shall be possible.

Therefore there shall be a new option needs_model, which takes a dictionary as value, which includes the configs for needs_extra_links and co.

I have to check if the usage ofneeds_model prohibits the usage of some other, already existing options.

Model defintiion needs tbd...

[twodrops]

I vote for this. It would be great to have a type-specific need definition, which is also self-contained.

[StephanKuempel]

Maybe the complete model could be defined by a json schema ?
Benefit would be:

• it would be easily usable from other program languages which may want to use this model information.
• can be used with existing json schema based services/tools
• can be easily used to stronger validate import needs json
• is a standard and widely known

Maybe, part of the already existing (very generic) needsfile.json schema could be used.

[ubmarco]

I tried an initial implementation of this using pydantic in #676. The docs are still missing, but I already at this early stage I think the solution checks all the boxes:

• arbitrary checks of needs is possible
• needs can be checked against all other needs
• pydantic is stable and well established
• pydantic models and constraints are written in Python which fits are target audience
• pydantic models are easy to read and write
• pydantic models can implement re-usability patterns (like model inheritance, re-usable fields)
• pydantic offers clear, precise and customizable validation error messages
• pydantic models can be used to derive needs_types, needs_extra_options and needs_extra_links in future (this needs some thoughts how to configure it completely as e.g. link arrow style does not belong to modeling)

Here is a Sphinx project example.

[mason3k]

Would be nice if needs_global_options could be supported on a per-needs-type basis as well, for defaults that only make sense for a certain needs type

[arwedus]

Would be nice if needs_global_options could be supported on a per-needs-type basis as well, for defaults that only make sense for a certain needs type

@danwos: I was about to request exactly that as a new issue, to have a per-directive default value for options 😆 . E.g. a requirement has default status "draft", but a test has a default status "implemented" (just an example, not sure if it makes sense).

This (sub) feature should be easy to implement, as we already have the same functionality via needextend (when you set an option for all needs of a certain type to a default value only if the option value is not '').

[arwedus]

@mason3k: This what we requested is actually already possible, see https://sphinx-needs.readthedocs.io/en/latest/configuration.html#filter-based-global-options

Set a filter based global option, and use type="req" (for example) as filter.

[ubmarco]

With the implementation of schema validation in Sphinx-Needs 6 I consider the requirements of the original post done.
Assigning extra options and extra links to certain need types is certainly possible with the new schema validation.