Replies: 1 comment 5 replies
-
Using jsonschema for defining needs types (like already mentioned in #332) should solve most of the problems with the currrent Schemas:
Instances: sw_component_1.json
req_sw_1.json
|
Beta Was this translation helpful? Give feedback.
5 replies
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Uh oh!
There was an error while loading. Please reload this page.
Uh oh!
There was an error while loading. Please reload this page.
-
Background
Sphinx-Needs is a tool which is currently used in our organization to handle safety critical artifacts following the
docs-as-code
methodology by 800+ developers. Firstly, kudos to the whole sphinx-needs team for this great tool 👍🏽As Sphinx-Needs is getting used more and more at enterprises, some of its conceptual limitations in creating model/type definitions needs to addressed. I am starting a discussion so that we can try to arrive at a solution together. Perhaps as part of a Sphinx-Needs 2.0.
Currrent main short-comings in model/type definition
conf.py
as the model definition languagePartially typed meta-model
The three main definition elements in Sphinx-Needs (
needs_types
,needs_extra_options
,needs_extra_links
) are not related to each other.For instance, the
needs_extra_options
are "global" and do not belong to anyneeds_types
. This simplicty in sphinx-needs however results in several issues, mainly:needs_warning
at runtime. This means sphinx-needs currently allows to creates need elements which does not conform to a schema and it can only be validated later. This is inefficient as a schema check can be done once (even statically before a build) and not "n" times at runtime for each instance as of now.A stricter meta-model could potentially look like this:
I was expecting that this would be different in the upcoming open-needs meta-model, but that does not seem to be the case. Therefore we need to check if we can arrive at a sphinx-needs solution.
GitHub Issue: #332
conf.py
as model definition languageSphinx-Needs currently uses
conf.py
for model/type definition. This information is needed not only for sphinx needs but for other tools/usecases as well.Information in
conf.py
cannot be easily reused by other tools. A neutral master definition language has the advantage of being available for other tools and also allows to generate any of the other needed artifacts above (even aconf.py
).Similar discussion here: #287
(The discussion focuses on reusing rST for model definitions with ConfAsDocs, but I find it not the correct metameta language for this usecase).
Beta Was this translation helpful? Give feedback.
All reactions