docs: Document the derived context feature

capellambse_context_diagrams/collectors/default.py

@@ -282,9 +282,15 @@ def add_derived_components_and_interfaces(
     derivator(diagram, data)
 
 
-def _derive_from_functions(
+def derive_from_functions(
     diagram: context.ContextDiagram, data: _elkjs.ELKInputData
-):
+) -> None:
+    """Derive Components from allocated functions of the context target.
+
+    A Component, a ComponentExchange and two ComponentPorts are added
+    to ``data``. These elements are prefixed with ``Derived-`` to
+    receive special styling in the serialization step.
+    """
     assert isinstance(diagram.target, cs.Component)
     ports = []
     for fnc in diagram.target.allocated_functions:
@@ -345,6 +351,7 @@ def _derive_from_functions(
 
 
 DERIVATORS = {
-    la.LogicalComponent: _derive_from_functions,
-    sa.SystemComponent: _derive_from_functions,
+    la.LogicalComponent: derive_from_functions,
+    sa.SystemComponent: derive_from_functions,
 }
+"""Objects to build derived contexts."""

docs/extras/derived.md

@@ -0,0 +1,37 @@
+<!--
+ ~ SPDX-FileCopyrightText: 2022 Copyright DB InfraGO AG and the capellambse-context-diagrams contributors
+ ~ SPDX-License-Identifier: Apache-2.0
+ -->
+
+# Derived diagram elements
+
+With capellambse-context-diagrams
+[`v0.2.36`](https://github.com/DSD-DBS/capellambse-context-diagrams/releases/tag/v0.2.36)
+a separate context is built. The elements are derived from the diagram target,
+i.e. the system of interest on which `context_diagram` was called on. The
+render parameter to enable this feature is called `display_derived_interfaces`
+and is available on:
+
+- `LogicalComponent`s and
+- `SystemComponent`s
+
+!!! example "Context Diagram with derived elements"
+
+    ```py
+    from capellambse import MelodyModel
+
+    lost = model.by_uuid("0d18f31b-9a13-4c54-9e63-a13dbf619a69")
+    diag = obj.context_diagram
+    diag.render(
+        "svgdiagram", display_derived_interfaces=True
+    ).save(pretty=True)
+    ```
+    <figure markdown>
+        <img src="../../assets/images/Context of Center-derived.svg" width="1000000">
+        <figcaption>Context diagram of <b>Center</b> with derived context</figcaption>
+    </figure>
+
+See [`the derivator
+functions`][capellambse_context_diagrams.collectors.default.DERIVATORS] to gain
+an overview over all supported capellambse types and the logic to derive
+elements.

docs/gen_images.py

@@ -36,6 +36,7 @@
 realization_fnc_uuid = "beaf5ba4-8fa9-4342-911f-0266bb29be45"
 realization_comp_uuid = "b9f9a83c-fb02-44f7-9123-9d86326de5f1"
 data_flow_uuid = "3b83b4ba-671a-4de8-9c07-a5c6b1d3c422"
+derived_uuid = "0d18f31b-9a13-4c54-9e63-a13dbf619a69"
 
 
 def generate_index_images() -> None:
@@ -153,6 +154,18 @@ def generate_data_flow_image() -> None:
         print(diag.render("svg", transparent_background=False), file=fd)
 
 
+def generate_derived_image() -> None:
+    diag: context.ContextDiagram = model.by_uuid(derived_uuid).context_diagram
+    params = {
+        "display_derived_interfaces": True,
+        "transparent_background": False,
+    }
+    with mkdocs_gen_files.open(
+        f"{str(dest / diag.name)}-derived.svg", "w"
+    ) as fd:
+        print(diag.render("svg", **params), file=fd)
+
+
 generate_index_images()
 generate_hierarchy_image()
 generate_no_symbol_images()
@@ -177,3 +190,4 @@ def generate_data_flow_image() -> None:
 generate_class_tree_images()
 generate_realization_view_images()
 generate_data_flow_image()
+generate_derived_image()

mkdocs.yml

@@ -89,11 +89,12 @@ nav:
   - Extras:
       - Filters: extras/filters.md
       - Styling: extras/styling.md
+      - 🔥 Derived 🔥: extras/derived.md
   - Tree View:
       - Overview: tree_view.md
   - Realization View:
       - Overview: realization_view.md
-  - 🔥 DataFlow View 🔥:
+  - DataFlow View:
       - Overview: data_flow_view.md
   - Code Reference: reference/
 

tests/test_context_diagrams.py

@@ -157,7 +157,6 @@ def test_context_diagram_with_derived_interfaces(
     obj = model.by_uuid(TEST_DERIVED_UUID)
 
     diag = obj.context_diagram
-    diag.display_derived_interfaces = True
-    diagram = diag.render(None)
+    diagram = diag.render(None, display_derived_interfaces=True)
 
     assert len(diagram) > 5