docs: Document the Realization View feature

capellambse_context_diagrams/collectors/realization_view.py

@@ -210,3 +210,4 @@ def find_layer(
     "ABOVE": collect_realized,
     "BELOW": collect_realizing,
 }
+"""The functions to receive the diagram elements for every layer."""

capellambse_context_diagrams/context.py

@@ -424,7 +424,7 @@ def uuid(self) -> str:  # type: ignore
     @property
     def name(self) -> str:  # type: ignore
         """Returns the name of the diagram."""
-        return f"Reailization view of {self.target.name}"
+        return f"Realization view of {self.target.name}"
 
     def _create_diagram(self, params: dict[str, t.Any]) -> cdiagram.Diagram:
         params.setdefault("depth", params.get("depth", 1))

docs/gen_images.py

@@ -33,6 +33,8 @@
 hierarchy_context = "16b4fcc5-548d-4721-b62a-d3d5b1c1d2eb"
 diagram_uuids = general_context_diagram_uuids | interface_context_diagram_uuids
 class_tree_uuid = "b7c7f442-377f-492c-90bf-331e66988bda"
+realization_fnc_uuid = "beaf5ba4-8fa9-4342-911f-0266bb29be45"
+realization_comp_uuid = "b9f9a83c-fb02-44f7-9123-9d86326de5f1"
 
 
 def generate_index_images() -> None:
@@ -112,6 +114,22 @@ def generate_class_tree_images() -> None:
         )
 
 
+def generate_realization_view_images() -> None:
+    for uuid in (realization_fnc_uuid, realization_comp_uuid):
+        obj = model.by_uuid(uuid)
+        diag = obj.realization_view
+        with mkdocs_gen_files.open(f"{str(dest / diag.name)}.svg", "w") as fd:
+            print(
+                diag.render(
+                    "svg",
+                    depth=3,
+                    search_direction="ALL",
+                    show_owners=True,
+                ),
+                file=fd,
+            )
+
+
 generate_index_images()
 generate_hierarchy_image()
 generate_no_symbol_images()
@@ -134,3 +152,4 @@ def generate_class_tree_images() -> None:
 )
 generate_styling_image(wizard, {}, "no_styles")
 generate_class_tree_images()
+generate_realization_view_images()

docs/realization_view.md

@@ -0,0 +1,70 @@
+<!--
+ ~ SPDX-FileCopyrightText: 2022 Copyright DB Netz AG and the capellambse-context-diagrams contributors
+ ~ SPDX-License-Identifier: Apache-2.0
+ -->
+
+# Tree View Diagram
+
+With release
+[`v0.5.42`](https://github.com/DSD-DBS/py-capellambse/releases/tag/v0.5.42) of
+[py-capellambse](https://github.com/DSD-DBS/py-capellambse) you can access the
+`.realization_view` on a Component or Function from any layer. A realization
+view diagram reveals the realization map that the layers of your model
+implement currently. The diagram elements are collected from the
+`.realized_components` or `.realized_functions` attribute for the direction
+`ABOVE` and `.realizing_components` or `.realizing_functions` for direction
+`BELOW`.
+
+??? example "Realization View Diagram of `LogicalFunction` `advise Harry`"
+
+    ``` py
+    import capellambse
+
+    model = capellambse.MelodyModel("tests/data/ContextDiagram.aird")
+    diag = model.by_uuid("beaf5ba4-8fa9-4342-911f-0266bb29be45").realization_view
+    diag.render(
+        "svgdiagram",
+        depth=3, # 1-3
+        search_direction="ALL", # BELOW; ABOVE and ALL
+        show_owners=True,
+    ).save_drawing(pretty=True)
+    ```
+    <figure markdown>
+        <img src="../assets/images/Realization view of advise Harry.svg">
+        <figcaption>[CDB] Realization View Diagram of advise Harry</figcaption>
+    </figure>
+
+??? example "Realization View Diagram of `PhysicalComponent` `Physical System`"
+
+    ``` py
+    import capellambse
+
+    model = capellambse.MelodyModel("tests/data/ContextDiagram.aird")
+    diag = model.by_uuid("b9f9a83c-fb02-44f7-9123-9d86326de5f1").realization_view
+    diag.render(
+        "svgdiagram",
+        depth=3,
+        search_direction="ALL",
+        show_owners=True,
+    ).save_drawing(pretty=True)
+    ```
+    <figure markdown>
+        <img src="../assets/images/Realization view of Physical System.svg">
+        <figcaption>[CDB] Realization View Diagram of Physical System</figcaption>
+    </figure>
+
+Additional rendering parameters enable showing owning functions or components,
+as well as the depth of traversion (i.e. `1`-`3`). They are put to display the
+maximum amount of diagram elements per default.
+
+??? bug "Alignment of diagram elements"
+
+    As of [[email protected]](https://eclipse.dev/elk/downloads/releasenotes/release-0.9.0.html) ELK's rectpacking algorithm isn't correctly using the
+    content alignment enumeration. While developing the Realization View
+    [a fix for the horizontal alignment was proposed](https://github.com/eclipse/elk/issues/989).
+
+## Check out the code
+
+To understand the collection have a look into the
+[`realization_view`][capellambse_context_diagrams.collectors.realization_view]
+module.

mkdocs.yml

@@ -91,6 +91,8 @@ nav:
       - Styling: extras/styling.md
   - Tree View:
       - Overview: tree_view.md
+  - Realization View:
+      - Overview: realization_view.md
   - Code Reference: reference/
 
 extra_css: