docs(cable-tree): Add docs

capellambse_context_diagrams/collectors/cable_tree.py

@@ -1,6 +1,7 @@
 # SPDX-FileCopyrightText: 2022 Copyright DB InfraGO AG and the capellambse-context-diagrams contributors
 # SPDX-License-Identifier: Apache-2.0
 
+"""This module defines the collector for the CableTreeDiagram."""
 from __future__ import annotations
 
 import copy
@@ -25,6 +26,7 @@ def __init__(
         params: dict[str, t.Any],
     ) -> None:
         self.diagram = diagram
+        self.diagram._port_label_position = "OUTSIDE"
         self.obj: m.ModelElement = self.diagram.target
         self.data = makers.make_diagram(diagram)
         self.data.layoutOptions = DEFAULT_LAYOUT_OPTIONS
@@ -36,18 +38,18 @@ def __init__(
     def __call__(self) -> _elkjs.ELKInputData:
         src_obj = self.obj.source
         tgt_obj = self.obj.target
-        target_link = self.make_edge(self.obj, src_obj, tgt_obj)
+        target_link = self._make_edge(self.obj, src_obj, tgt_obj)
         target_link.layoutOptions = copy.deepcopy(
             _elkjs.EDGE_STRAIGHTENING_LAYOUT_OPTIONS
         )
-        self.make_tree(src_obj)
-        self.make_tree(tgt_obj, reverse=True)
+        self._make_tree(src_obj)
+        self._make_tree(tgt_obj, reverse=True)
         return self.data
 
-    def make_tree(
+    def _make_tree(
         self, port_obj: m.ModelElement, reverse: bool = False
     ) -> _elkjs.ELKInputChild:
-        box = self.make_port_and_owner(port_obj)
+        box = self._make_port_and_owner(port_obj)
         for link in port_obj.links:
             if self.edges.get(link.uuid):
                 continue
@@ -56,51 +58,45 @@ def make_tree(
             else:
                 obj = link.source
             if reverse:
-                self.make_edge(link, obj, port_obj)
+                self._make_edge(link, obj, port_obj)
             else:
-                self.make_edge(link, port_obj, obj)
-            self.make_tree(obj, reverse=reverse)
+                self._make_edge(link, port_obj, obj)
+            self._make_tree(obj, reverse=reverse)
         return box
 
-    def make_edge(
+    def _make_edge(
         self,
         link: m.ModelElement,
         src_obj: m.ModelElement,
         tgt_obj: m.ModelElement,
     ) -> _elkjs.ELKInputEdge:
         edge = _elkjs.ELKInputEdge(
-            id=link.uuid, sources=[src_obj.uuid], targets=[tgt_obj.uuid]
+            id=link.uuid,
+            sources=[src_obj.uuid],
+            targets=[tgt_obj.uuid],
+            labels=makers.make_label(
+                link.name,
+            ),
         )
         self.data.edges.append(edge)
         self.edges[link.uuid] = edge
         return edge
 
-    def _make_box(
-        self,
-        obj: t.Any,
-        **kwargs: t.Any,
-    ) -> _elkjs.ELKInputChild:
-        box = makers.make_box(
-            obj,
-            **kwargs,
-        )
-        self.boxes[obj.uuid] = box
-        return box
-
-    def make_port_and_owner(
+    def _make_port_and_owner(
         self, port_obj: m.ModelElement
     ) -> _elkjs.ELKInputChild:
         owner_obj = port_obj.owner
         if not (box := self.boxes.get(owner_obj.uuid)):
-            box = self._make_box(
+            box = makers.make_box(
                 owner_obj,
                 layout_options=makers.DEFAULT_LABEL_LAYOUT_OPTIONS,
             )
+            self.boxes[owner_obj.uuid] = box
             self.data.children.append(box)
         if port := self.ports.get(port_obj.uuid):
             return box
         port = makers.make_port(port_obj.uuid)
-        # port.labels = makers.make_label(port_obj.name)
+        port.labels = makers.make_label(port_obj.name)
         box.ports.append(port)
         self.ports[port_obj.uuid] = port
         return box
@@ -109,4 +105,5 @@ def make_port_and_owner(
 def collector(
     diagram: context.ContextDiagram, params: dict[str, t.Any]
 ) -> _elkjs.ELKInputData:
+    """Main collector function for the CableTreeDiagram."""
     return CableTreeCollector(diagram, params)()

docs/cable_tree.md

@@ -0,0 +1,28 @@
+<!--
+ ~ SPDX-FileCopyrightText: 2022 Copyright DB InfraGO AG and the capellambse-context-diagrams contributors
+ ~ SPDX-License-Identifier: Apache-2.0
+ -->
+
+# Cable Tree View Diagram
+
+The `Cable Tree View` diagram visualizes the cable connections between ports. You can access `.cable_tree` on any `pa.PhysicalLink` element.
+
+??? example "Cable Tree View of Control Signal"
+
+    ``` py
+    import capellambse
+
+    model = capellambse.MelodyModel("tests/data/ContextDiagram.aird")
+    diag = model.by_uuid("5c55b11b-4911-40fb-9c4c-f1363dad846e").cable_tree
+    diag.render("svgdiagram").save(pretty=True)
+    ```
+    <figure markdown>
+        <img src="../assets/images/Cable Tree View of Control Signal.svg">
+        <figcaption>[LAB] Cable Tree View of Control Signal</figcaption>
+    </figure>
+
+## Check out the code
+
+To understand the collection have a look into the
+[`cable_tree`][capellambse_context_diagrams.collectors.cable_tree]
+module.

docs/gen_images.py

@@ -43,6 +43,7 @@
 realization_comp_uuid = "b9f9a83c-fb02-44f7-9123-9d86326de5f1"
 data_flow_uuid = "3b83b4ba-671a-4de8-9c07-a5c6b1d3c422"
 derived_uuid = "47c3130b-ec39-4365-a77a-5ab6365d1e2e"
+cable_tree_uuid = "5c55b11b-4911-40fb-9c4c-f1363dad846e"
 
 
 def generate_index_images() -> None:
@@ -206,6 +207,14 @@ def generate_interface_with_hide_interface_image():
         print(diag.render("svg", **params), file=fd)
 
 
+def generate_cable_tree_image():
+    diag: context.CableTreeViewDiagram = model.by_uuid(
+        cable_tree_uuid
+    ).cable_tree
+    with mkdocs_gen_files.open(f"{str(dest / diag.name)}.svg", "w") as fd:
+        print(diag.render("svg", transparent_background=False), file=fd)
+
+
 generate_index_images()
 generate_hierarchy_image()
 generate_symbol_images()
@@ -234,3 +243,4 @@ def generate_interface_with_hide_interface_image():
 generate_derived_image()
 generate_interface_with_hide_functions_image()
 generate_interface_with_hide_interface_image()
+generate_cable_tree_image()

mkdocs.yml

@@ -96,6 +96,8 @@ nav:
       - Overview: realization_view.md
   - DataFlow View:
       - Overview: data_flow_view.md
+  - Cable Tree View:
+      - Overview: cable_tree.md
   - Extras:
       - Filters: extras/filters.md
       - Styling: extras/styling.md

tests/test_cable_tree_views.py

@@ -0,0 +1,18 @@
+# SPDX-FileCopyrightText: 2022 Copyright DB InfraGO AG and the capellambse-context-diagrams contributors
+# SPDX-License-Identifier: Apache-2.0
+
+import capellambse
+import pytest
+
+
+@pytest.mark.parametrize("uuid", ["5c55b11b-4911-40fb-9c4c-f1363dad846e"])
+@pytest.mark.parametrize("fmt", ["svgdiagram", "svg", None])
+def test_exchange_item_relation_views(
+    model: capellambse.MelodyModel, uuid: str, fmt: str
+) -> None:
+    obj = model.by_uuid(uuid)
+
+    diag = obj.cable_tree
+    diag.render("svgdiagram").save(pretty=True)
+
+    assert diag.render(fmt)