feat: draw_metamodel in docs

Author: AlexanderLanin

docs/internals/requirements/requirements.rst

@@ -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?
+
+    .. 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"],
+      )}}
+
 
 
 ----------
@@ -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
@@ -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
@@ -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
@@ -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
 -------------------------
@@ -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
@@ -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
@@ -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",
+        ],
+      )}}
+
 --------------------------
 Architecture Attributes
 --------------------------
@@ -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",
+           ],
+         )}}
 
 
 ------------------------
@@ -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(
+        [
+          "feat_req",
+          "comp_req",
+          "feat_arc_sta",
+          "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
@@ -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
 ##########################
 

src/extensions/score_draw_uml_funcs/__init__.py

@@ -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,

src/extensions/score_metamodel/__init__.py

@@ -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
 
@@ -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()
@@ -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 = (
@@ -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(