docs: Update docs

Add interface section and document `hide_functions`.
DSD-DBS · Jun 25, 2024 · d677e0d · d677e0d
1 parent ce9eb22
commit d677e0d
Show file tree

Hide file tree

Showing 4 changed files with 81 additions and 45 deletions.
diff --git a/docs/gen_images.py b/docs/gen_images.py
@@ -177,6 +177,16 @@ def generate_derived_image() -> None:
         print(diag.render("svg", **params), file=fd)
 
 
+def generate_interface_with_hide_functions_image():
+    uuid = interface_context_diagram_uuids["Interface"][0]
+    diag: context.ContextDiagram = model.by_uuid(uuid).context_diagram
+    params = {"hide_functions": True}
+    with mkdocs_gen_files.open(
+        f"{str(dest / diag.name)}-hide-functions.svg", "w"
+    ) as fd:
+        print(diag.render("svg", **params), file=fd)
+
+
 generate_index_images()
 generate_hierarchy_image()
 generate_no_symbol_images()
@@ -202,3 +212,4 @@ def generate_derived_image() -> None:
 generate_realization_view_images()
 generate_data_flow_image()
 generate_derived_image()
+generate_interface_with_hide_functions_image()
diff --git a/docs/index.md b/docs/index.md
@@ -213,52 +213,19 @@ Hierarchy is identified and supported:
         <figcaption>Context diagram of Hierarchy LogicalComponenet with type [LAB]</figcaption>
     </figure>
 
-### Interfaces (aka ComponentExchanges)
-
-The data is collected by [get_elkdata_for_exchanges][capellambse_context_diagrams.collectors.exchanges.get_elkdata_for_exchanges] which is using the [`InterfaceContextCollector`][capellambse_context_diagrams.collectors.exchanges.InterfaceContextCollector] underneath.
-
-??? example "[`fa.ComponentExchange`][capellambse.model.crosslayer.fa.ComponentExchange]"
-
-    ``` py
-    import capellambse
-
-    model = capellambse.MelodyModel("tests/data/ContextDiagram.aird")
-    diag = model.by_uuid("3ef23099-ce9a-4f7d-812f-935f47e7938d").context_diagram
-    diag.render("svgdiagram").save(pretty=True)
-    ```
-    <figure markdown>
-        <img src="assets/images/Interface Context of Left to right.svg" width="1000000">
-        <figcaption>Interface context diagram of Left to right LogicalComponentExchange with type [LAB]</figcaption>
-    </figure>
-
-??? example "Include the interface the ([`fa.ComponentExchange`][capellambse.model.crosslayer.fa.ComponentExchange])"
-
-    ``` py
-    import capellambse
-
-    model = capellambse.MelodyModel("tests/data/ContextDiagram.aird")
-    diag = model.by_uuid("fbb7f735-3c1f-48de-9791-179d35ca7b98").context_diagram
-    diag.render("svgdiagram", include_interface=True).save(pretty=True)
-    ```
-    <figure markdown>
-        <img src="assets/images/Interface Context of Interface.svg" width="1000000">
-        <figcaption>Interface context diagram of Interface LogicalComponentExchange with type [LAB]</figcaption>
-    </figure>
-
-!!! warning "Interface context only supported for the LogicalComponentExchanges"
-
 ### Customized edge routing
 
 !!! note "Custom routing"
-The routing differs from [ELK's Layered Algorithm](https://www.eclipse.org/elk/reference/algorithms/org-eclipse-elk-layered.html): The flow display is disrupted!
-We configure exchanges such that they appear in between the context
-participants. This decision breaks the display of data flow which is one
-of the main aims of ELK's Layered algorithm. However this lets counter
-flow exchanges routes lengths and bendpoints increase.
+
+    The routing differs from [ELK's Layered Algorithm](https://www.eclipse.org/elk/reference/algorithms/org-eclipse-elk-layered.html): The flow display is disrupted!
+    We configure exchanges such that they appear in between the context
+    participants. This decision breaks the display of data flow which is one
+    of the main aims of ELK's Layered algorithm. However this lets counter
+    flow exchanges routes lengths and bendpoints increase.
 
     <figure markdown>
-        <img src="assets/images/Context of Weird guy.svg" width="1000000">
-        <figcaption>Context diagram of Weird guy SystemFunction</figcaption>
+    <img src="assets/images/Context of Weird guy.svg" width="1000000">
+    <figcaption>Context diagram of Weird guy SystemFunction</figcaption>
     </figure>
 
 ---

diff --git a/docs/interface.md b/docs/interface.md
@@ -0,0 +1,56 @@
+<!--
+ ~ SPDX-FileCopyrightText: 2022 Copyright DB InfraGO AG and the capellambse-context-diagrams contributors
+ ~ SPDX-License-Identifier: Apache-2.0
+ -->
+
+# Interfaces (aka ComponentExchanges)
+
+The data is collected by [get_elkdata_for_exchanges][capellambse_context_diagrams.collectors.exchanges.get_elkdata_for_exchanges] which is using the [`InterfaceContextCollector`][capellambse_context_diagrams.collectors.exchanges.InterfaceContextCollector] underneath.
+
+You can render an interface context view just with `context_diagram` on any
+[`fa.ComponentExchange`][capellambse.model.crosslayer.fa.ComponentExchange]:
+
+``` py
+import capellambse
+
+model = capellambse.MelodyModel("tests/data/ContextDiagram.aird")
+diag = model.by_uuid("3ef23099-ce9a-4f7d-812f-935f47e7938d").context_diagram
+diag.render("svgdiagram").save(pretty=True)
+```
+
+<figure markdown>
+<img src="../assets/images/Interface Context of Left to right.svg" width="1000000">
+<figcaption>Interface context diagram of Left to right LogicalComponentExchange with type [LAB]</figcaption>
+</figure>
+
+## Include the interface itself in the context
+??? example "Include the interface in the Interface Context"
+
+    ``` py
+    import capellambse
+
+    model = capellambse.MelodyModel("tests/data/ContextDiagram.aird")
+    diag = model.by_uuid("fbb7f735-3c1f-48de-9791-179d35ca7b98").context_diagram
+    diag.render("svgdiagram", include_interface=True).save(pretty=True)
+    ```
+    <figure markdown>
+        <img src="../assets/images/Interface Context of Interface.svg" width="1000000">
+        <figcaption>Interface context diagram of Interface LogicalComponentExchange with type [LAB]</figcaption>
+    </figure>
+
+## Hide functional model elements from the context
+??? example "Hide functions and functional exchanges in the Interface Context"
+
+    ``` py
+    import capellambse
+
+    model = capellambse.MelodyModel("tests/data/ContextDiagram.aird")
+    diag = model.by_uuid("fbb7f735-3c1f-48de-9791-179d35ca7b98").context_diagram
+    diag.render("svgdiagram", hide_functions=True).save(pretty=True)
+    ```
+    <figure markdown>
+        <img src="../assets/images/Interface Context of Interface-hide-functions.svg" width="1000000">
+        <figcaption>Interface context diagram of Interface LogicalComponentExchange with type [LAB]</figcaption>
+    </figure>
+
+!!! warning "Interface context only supported for the LogicalComponentExchanges"
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -86,16 +86,18 @@ nav:
       - Quickstart: quickstart.md
       - Credits: credits.md
       - License: license.md
-  - Extras:
-      - Filters: extras/filters.md
-      - Styling: extras/styling.md
-      - 🔥 Derived 🔥: extras/derived.md
+  - Interface Context View:
+      - Overview: interface.md
   - Tree View:
       - Overview: tree_view.md
   - Realization View:
       - Overview: realization_view.md
   - DataFlow View:
       - Overview: data_flow_view.md
+  - Extras:
+      - Filters: extras/filters.md
+      - Styling: extras/styling.md
+      - Derived: extras/derived.md
   - Code Reference: reference/
 
 extra_css: