From d677e0d55fda3a7ee79595e7da20918de308d4e2 Mon Sep 17 00:00:00 2001 From: ewuerger <ernst.wuerger@gmail.com> Date: Tue, 25 Jun 2024 14:49:43 +0200 Subject: [PATCH] docs: Update docs Add interface section and document `hide_functions`. --- docs/gen_images.py | 11 +++++++++ docs/index.md | 49 +++++++--------------------------------- docs/interface.md | 56 ++++++++++++++++++++++++++++++++++++++++++++++ mkdocs.yml | 10 +++++---- 4 files changed, 81 insertions(+), 45 deletions(-) create mode 100644 docs/interface.md diff --git a/docs/gen_images.py b/docs/gen_images.py index 2a884276..96f0e71b 100644 --- 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 index de752e4e..0f5083ed 100644 --- 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 new file mode 100644 index 00000000..dafe286e --- /dev/null +++ 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 index 7ff20180..c3748d25 100644 --- 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: