Skip to content

feat: draw_metamodel in docs #336

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
AlexanderLanin wants to merge 3 commits into
base: main
Choose a base branch
from
Draft

feat: draw_metamodel in docs #336

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
ad9d149
feat: draw_metamodel in docs
AlexanderLanin Jan 8, 2026
3845f5a
Fix formatting of requirements table in documentation
RolandJentschETAS Jan 9, 2026
1de9f31
Fix formatting issues in requirements documentation
RolandJentschETAS Jan 9, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
129 changes: 118 additions & 11 deletions docs/internals/requirements/requirements.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -221,6 +221,19 @@ This section provides an overview of current process requirements and their clar
* all architecture elements defined in :need:`tool_req__docs_arch_types`.
* all safety analysis elements defined in :need:`tool_req__docs_saf_types`.

.. admonition:: How is it currently implemented in the current docs-as-code metamodel.yml?
Copy link
Contributor

@a-zw a-zw Jan 9, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pulling in parts of the implementation into a requirement is weird from a process point of view. It implies testing is not necessary because the requirement implicitly always reflects what is implemented.

Alternatively, we don't consider metamodel.yaml as implementation but as a requirements artifact. In that case, it should not be placed deep within the code.

Copy link
Member Author

@AlexanderLanin AlexanderLanin Jan 9, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah, metamodel could be the requirement. Maybe.
Maybe we need to drop tool requirements.
Maybe we copy process requirements as tool requirements.
etc

Copy link
Member Author

@AlexanderLanin AlexanderLanin Jan 9, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

source code link is actually exactly the same. It shows implementation "in" the requirement.


.. needuml::

{{draw_metamodel(
[
"stkh_req", "feat_req", "comp_req", "aou_req",
"feat_arc_sta", "feat", "logic_arc_int", "logic_arc_int_op", "comp_arc_sta", "comp", "real_arc_int", "real_arc_int_op",
"feat_saf_fmea", "comp_saf_fmea", "feat_saf_dfa", "comp_saf_dfa",
],
attributes=["status"],
)}}



----------
Expand Down Expand Up @@ -271,6 +284,12 @@ Versioning
* Tool Verification Report (doc_tool)
* Change Request is also a generic document

.. admonition:: How is it currently implemented in the current docs-as-code metamodel.yml?

.. needuml::

{{draw_metamodel(types=["document", "doc_tool"])}}

.. tool_req:: Mandatory attributes of Generic Documents
:id: tool_req__docs_doc_generic_mandatory
:tags: Documents
Expand All @@ -287,6 +306,12 @@ Versioning
* safety
* realizes

.. admonition:: How is it currently implemented in the current docs-as-code metamodel.yml?

.. needuml::

{{draw_metamodel("document", attributes=["status", "security", "safety", "realizes"])}}

.. tool_req:: Mandatory Document attributes
:id: tool_req__docs_doc_attr
:tags: Documents
Expand All @@ -307,6 +332,11 @@ Versioning
* approver
* reviewer

.. admonition:: How is it currently implemented in the current docs-as-code metamodel.yml?

.. needuml::

{{draw_metamodel(["document", "doc_tool"], attributes=["title", "author", "approver", "reviewer"])}}

.. tool_req:: Document author is autofilled
:id: tool_req__docs_doc_attr_author_autofill
Expand Down Expand Up @@ -388,6 +418,16 @@ Mapping
* Process requirement (gd_req)
* Tool requirement (tool_req)

.. admonition:: How is it currently implemented in the current docs-as-code metamodel.yml?

.. needuml::

{{draw_metamodel(
[
"stkh_req", "feat_req", "comp_req", "aou_req", "gd_req", "tool_req",
],
)}}

-------------------------
🏷️ Attributes
-------------------------
Expand All @@ -401,6 +441,13 @@ Mapping

Docs-as-Code shall enforce that each stakeholder requirement (stkh_req) contains a ``rationale`` attribute.

.. admonition:: How is it currently implemented in the current docs-as-code metamodel.yml?

.. needuml::

{{draw_metamodel(["stkh_req"], attributes=["rationale"])}}


.. tool_req:: Enforces requirement type classification
:id: tool_req__docs_req_attr_reqtype
:tags: Requirements
Expand Down Expand Up @@ -507,6 +554,18 @@ Mapping
.. note::
Certain tool requirements do not have a matching process requirement.

.. admonition:: How is it currently implemented in the current docs-as-code metamodel.yml?

.. needuml::

{{draw_metamodel(
[
"stkh_req", "feat_req", "comp_req", "gd_req", "tool_req", "workflow"
],
links="satisfies",
)}}


.. tool_req:: Safety: enforce safe linking
:id: tool_req__docs_common_attr_safety_link_check
:tags: Common Attributes
Expand Down Expand Up @@ -544,6 +603,16 @@ Mapping
* Interface (real_arc_int)
* Interface Operation (real_arc_int_op)

.. admonition:: How is it currently implemented in the current docs-as-code metamodel.yml?

.. needuml::

{{draw_metamodel(
[
"feat_arc_sta", "feat", "logic_arc_int", "logic_arc_int_op", "comp_arc_sta", "comp", "real_arc_int", "real_arc_int_op",
Copy link
Contributor

@RolandJentschETAS RolandJentschETAS Jan 9, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is the output alphabetical ordered ? I would like to have it in the original given order or at least by option sorted. The reason is to create an blocks according to the given requirement. Is there any possibility to add artificial line breaks?

Copy link
Member Author

@AlexanderLanin AlexanderLanin Jan 9, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The output is currently alphabetical... thought error. We can use the user provided order.

But arranging images by providing the arguments here in a specific order... that sounds like a suicide risk.

],
)}}

--------------------------
Architecture Attributes
--------------------------
Expand All @@ -564,8 +633,24 @@ Architecture Attributes
* Safety
* Security
* Status
* UID
* ID (implicitly enforced by sphinx-needs)

.. admonition:: How is it currently implemented in the current docs-as-code metamodel.yml?

.. needuml::

{{draw_metamodel(
[
"feat_arc_sta", "feat", "logic_arc_int", "logic_arc_int_op", "comp_arc_sta", "comp", "real_arc_int", "real_arc_int_op",
],
attributes=[
"fulfils",
"safety",
"security",
"status",
"id",
],
)}}


------------------------
Expand Down Expand Up @@ -601,6 +686,24 @@ Architecture Attributes
real_arc_int comp_req
==================================== ==========================================

.. admonition:: How is it currently implemented in the current docs-as-code metamodel.yml?

.. needuml::

{{draw_metamodel(
Copy link
Contributor

@RolandJentschETAS RolandJentschETAS Jan 9, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The picture shows only 6 of 8 components. The interfaces are missing. I would like to show them, also if there are no links available.

Copy link
Member Author

@AlexanderLanin AlexanderLanin Jan 9, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In my examples I've added only the stuff that was mentioned in exactly that requirement. But that's one of the main questions: how do use this draw_metamodel feature in a way that actually helps us.

[
"feat_req",
"comp_req",
"feat_arc_sta",
Copy link
Contributor

@masc2023 masc2023 Jan 9, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If this is rendered here, and it shows missing feat_arc_sta is not implemented yet as not drawn, then it already helps for verification here

Image

Copy link
Member Author

@AlexanderLanin AlexanderLanin Jan 9, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Exactly. We could also add some error reporting... but I'm afraid that we would reimplement the metamodel in the draw functions / make them overly strict in what exactly they can actually draw.

"feat_arc_dyn",
"logic_arc_int"
"comp_arc_sta",
"comp_arc_dyn",
"real_arc_int"
],
links=["fulfils"],
attributes=False
)}}

.. tool_req:: Ensure safety architecture elements link a safety requirement
:id: tool_req__docs_arch_link_safety_to_req
Expand Down Expand Up @@ -675,6 +778,7 @@ Architecture Attributes
but are still defined as architectural elements, which means they have the properties of
architectural elements.


💻 Detailed Design & Code
##########################

Expand Down Expand Up @@ -778,9 +882,9 @@ Testing

Docs-as-Code shall ensure that test cases link to requirements on the correct level:

- If Partially/FullyVerifies are set in Feature Integration Test these shall link to Feature Requirements
- If Partially/FullyVerifies are set in Component Integration Test these shall link to Component Requirements
- If Partially/FullyVerifies are set in Unit Test these shall link to Component Requirements
- If Partially/FullyVerifies are set in Feature Integration Test these shall link to Feature Requirements
- If Partially/FullyVerifies are set in Component Integration Test these shall link to Component Requirements
- If Partially/FullyVerifies are set in Unit Test these shall link to Component Requirements


🧪 Tool Verification Reports
Expand Down Expand Up @@ -890,7 +994,7 @@ Testing
gd_req__saf_attr_uid,
:parent_covered: YES

Docs-As-Code shall support the following need types:
Docs-As-Code shall support the following need types:

* Feature FMEA (Failure Modes and Effect Analysis) -> ``feat_saf_fmea``
* Component FMEA (Failure Modes and Effect Analysis) -> ``comp_saf_fmea``
Expand Down Expand Up @@ -998,14 +1102,17 @@ Testing
Docs-As-Code shall enforce that needs of type :need:`tool_req__docs_saf_types` have a
`violates` links to at least one dynamic / static diagram according to the table.

| Source | Target |
| -- | -- |
| feat_saf_dfa | feat_arc_sta |
| comp_saf_dfa | comp_arc_sta |
+---------------+--------------+
| Source | Target |
+===============+==============+
| feat_saf_dfa | feat_arc_sta |
+---------------+--------------+
| comp_saf_dfa | comp_arc_sta |
+---------------+--------------+
| feat_saf_fmea | feat_arc_dyn |
+---------------+--------------+
| comp_saf_fmea | comp_arc_dyn |


+---------------+--------------+

.. tool_req:: FMEA: fault id attribute
:id: tool_req__docs_saf_attr_fmea_fault_id
Expand Down
6 changes: 5 additions & 1 deletion src/extensions/score_draw_uml_funcs/__init__.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -60,7 +60,11 @@


def setup(app: Sphinx) -> dict[str, object]:
app.config.needs_render_context = draw_uml_function_context
# Extend the needs_render_context with our drawing functions
app.config.needs_render_context = (
app.config.needs_render_context or {}
) | draw_uml_function_context

return {
"version": "0.1",
"parallel_read_safe": True,
Expand Down
29 changes: 21 additions & 8 deletions src/extensions/score_metamodel/__init__.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,9 +17,11 @@
from pathlib import Path

from sphinx.application import Sphinx
from sphinx.environment import BuildEnvironment
from sphinx_needs import logging
from sphinx_needs.data import NeedsInfoType, NeedsView, SphinxNeedsData

from src.extensions.score_metamodel.draw_metamodel import DrawMetamodel
from src.extensions.score_metamodel.external_needs import connect_external_needs
from src.extensions.score_metamodel.log import CheckLogger

Expand Down Expand Up @@ -101,13 +103,6 @@ def _run_checks(app: Sphinx, exception: Exception | None) -> None:
if exception:
return

# First of all postprocess the need links to convert
# type names into actual need types.
# This must be done before any checks are run.
# And it must be done after config was hashed, otherwise
# the config hash would include recusive linking between types.
postprocess_need_links(app.config.needs_types)

# Filter out external needs, as checks are only intended to be run
# on internal needs.
needs_all_needs = SphinxNeedsData(app.env).get_needs_view()
Expand Down Expand Up @@ -201,13 +196,17 @@ def _resolve_linkable_types(
return linkable_types


def postprocess_need_links(needs_types_list: list[ScoreNeedType]):
def postprocess_need_links(
app: Sphinx, _env: BuildEnvironment, _docnames: list[str]
) -> None:
"""Convert link option strings into lists of target need types.

If a link value starts with '^' it is treated as a regex and left
unchanged. Otherwise it is a comma-separated list of type names which
are resolved to the corresponding ScoreNeedTypes.
"""
needs_types_list: list[ScoreNeedType] = app.config.needs_types

for need_type in needs_types_list:
try:
link_dicts = (
Expand Down Expand Up @@ -250,11 +249,25 @@ def setup(app: Sphinx) -> dict[str, str | bool]:
app.config.needs_reproducible_json = True
app.config.needs_json_remove_defaults = True

# Extend the needs_render_context with our drawing functions
app.config.needs_render_context = (app.config.needs_render_context or {}) | {
"draw_metamodel": DrawMetamodel(app.config),
}

# sphinx-collections runs on default prio 500.
# We need to populate the sphinx-collections config before that happens.
# --> 499
_ = app.connect("config-inited", connect_external_needs, priority=499)

# Postprocess the need links to convert type names into actual need types.
# This must be done before any checks are run.
# And it must be done after config was hashed, otherwise
# the config hash would include recusive linking between types.
# Note that needs_config_writer also runs at 999. Our postprocessing must happen
# after needs_config_writer has done its job (for now).
# So needs_config_writer must be included before score_metamodel in extensions list.
_ = app.connect("env-before-read-docs", postprocess_need_links, priority=999)

discover_checks()

app.add_config_value(
Expand Down
Loading
Loading