merge: Fix diagram cache documentation

capellambse/_diagram_cache.py

@@ -47,7 +47,9 @@
 )
 
 
-class _IndexEntry(t.TypedDict):
+class IndexEntry(t.TypedDict):
+    """An entry for the index JSON file."""
+
     uuid: str
     name: str
     type: modeltypes.DiagramType
@@ -143,13 +145,13 @@ def _copy_images(
     destdir: pathlib.Path,
     extension: str,
     background: bool,
-) -> list[_IndexEntry]:
+) -> list[IndexEntry]:
     name_counts = collections.defaultdict[str, int](lambda: -1)
-    index: list[_IndexEntry] = []
+    index: list[IndexEntry] = []
     files = {i.name: i for i in srcdir.glob("**/*") if i.is_file()}
 
     for i in model.diagrams:
-        entry: _IndexEntry = {
+        entry: IndexEntry = {
             "uuid": i.uuid,
             "name": i.name,
             "type": i.type,
@@ -244,7 +246,7 @@ def _write_index(
     model: capellambse.MelodyModel,
     extension: str,
     dest: pathlib.Path,
-    index: list[_IndexEntry],
+    index: list[IndexEntry],
 ) -> None:
     now = datetime.datetime.now().strftime("%A, %Y-%m-%d %H:%M:%S")
     title = f"Capella diagram cache for {model.name!r}"
@@ -261,7 +263,7 @@ def _write_index(
         body := E.body(E.h1(title), E.p({"class": "small"}, "Created: ", now)),
     )
 
-    def sortkey(entry: _IndexEntry):
+    def sortkey(entry: IndexEntry):
         try:
             vp_index = VIEWPOINT_ORDER.index(entry["viewpoint"])
         except ValueError:
@@ -290,6 +292,8 @@ def sortkey(entry: _IndexEntry):
 
 
 class IndexEncoder(json.JSONEncoder):
+    """A JSON encoder for the index file."""
+
     def default(self, o):
         if isinstance(o, modeltypes.DiagramType):
             return o.name

capellambse/diagram_cache.py

@@ -9,6 +9,9 @@
 import capellambse
 from capellambse import _diagram_cache, cli_helpers
 
+# pylint: disable=unused-import
+from capellambse._diagram_cache import IndexEntry
+
 try:
     import click
 except ImportError:

capellambse/model/__init__.py

@@ -512,8 +512,11 @@ def update_diagram_cache(
             list of dictionaries, each representing a diagram in the
             model. The dictionaries come with the keys
 
+            - uuid: The unique ID of the diagram
             - name: Name of the diagram as it has been set in Capella
-            - uuid: The UUID of the diagram
+            - type: The diagram type as it was created in Capella
+            - viewpoint: The source layer from where the representation
+              is loaded from. It is ``Common`` for layerless diagrams.
             - success: A boolean stating if a diagram has been exported
               from Capella