test: Enable doctests on source modules

Author: Wuestengecko

pyproject.toml

@@ -253,12 +253,13 @@ ignore_missing_imports = true
 [tool.pytest.ini_options]
 addopts = """
   -W error::pytest.PytestUnraisableExceptionWarning
+  --doctest-modules
   --import-mode=importlib
   --strict-config
   --strict-markers
   --tb=short
 """
-testpaths = ["tests"]
+testpaths = ["src/capellambse", "tests"]
 xfail_strict = true
 
 [tool.ruff]

src/capellambse/_scripts/repl.py

@@ -294,10 +294,11 @@ def showxml(obj: capellambse.ModelObject | etree._Element) -> None:
 
     Examples
     --------
-    >>> my_obj = model.search("LogicalComponent").by_name("My Component")
+    >>> my_obj = model.search("LogicalComponent").by_name("School")
     >>> showxml(my_obj)
-    <ownedLogicalComponents name="My Component">
-      ...
+    <ownedLogicalComponents xsi:type="org.polarsys.capella.core.data.la:LogicalComponent"
+        id="a58821df-c5b4-4958-9455-0d30755be6b1" name="School">
+    ...
     </ownedLogicalComponents>
     """
     if isinstance(obj, etree._Element):
@@ -319,10 +320,10 @@ def fzf(
     Examples
     --------
     >>> # Select a LogicalComponent by name
-    >>> obj = fzf(model.search("LogicalComponent"))
+    >>> obj = fzf(model.search("LogicalComponent"))                             # doctest: +SKIP
 
     >>> # Select a ComponentExchange by the name of its target component
-    >>> obj = fzf(model.search("ComponentExchange"), "target.parent.name")
+    >>> obj = fzf(model.search("ComponentExchange"), "target.parent.name")      # doctest: +SKIP
     """
 
     def repr(obj):

src/capellambse/conftest.py

@@ -0,0 +1,21 @@
+# SPDX-FileCopyrightText: Copyright DB InfraGO AG
+# SPDX-License-Identifier: Apache-2.0
+"""Test fixtures for capellambse's doctests."""
+
+import pytest
+
+import capellambse
+from capellambse import helpers
+
+
+@pytest.fixture(autouse=True)
+def load_test_models(doctest_namespace):
+    model = capellambse.loadcli("test-5.0")
+    doctest_namespace["model"] = model
+    doctest_namespace["loader"] = model._loader
+
+
+@pytest.fixture(autouse=True)
+def deterministic_ids():
+    with helpers.deterministic_ids():
+        yield

src/capellambse/extensions/pvmt/_objects.py

@@ -34,10 +34,10 @@ class ObjectPVMT:
 
        >>> obj = model.by_uuid("08e02248-504d-4ed8-a295-c7682a614f66")
        >>> obj.pvmt["DarkMagic.Power.Max"]
-       1600
+       1600.0
        >>> obj.pvmt["DarkMagic.Power.Max"] = 2000
        >>> obj.pvmt["DarkMagic.Power.Max"]
-       2000
+       2000.0
 
     2. It's also possible to retrieve a managed group with the same
        syntax, by omitting the 'property' part of the path. The
@@ -46,7 +46,7 @@ class ObjectPVMT:
 
        >>> power = obj.pvmt["DarkMagic.Power"]
        >>> power["Max"]
-       2000
+       2000.0
     """
 
     _model: capellambse.MelodyModel

src/capellambse/loader/core.py

@@ -787,13 +787,14 @@ def new_uuid(
         .. note:: You still need to call :meth:`idcache_index()` on the
             newly inserted element!
 
-        Example usage::
-
-            >>> with ldr.new_uuid(parent_elm) as obj_id:
-            ...     child_elm = parent_elm.makeelement("ownedObjects")
-            ...     child_elm.set("id", obj_id)
-            ...     parent_elm.append(child_elm)
-            ...     ldr.idcache_index(child_elm)
+        Example usage:
+
+        >>> parent_elm = loader["08e02248-504d-4ed8-a295-c7682a614f66"]
+        >>> with loader.new_uuid(parent_elm) as obj_id:
+        ...     child_elm = parent_elm.makeelement("ownedObjects")
+        ...     child_elm.set("id", obj_id)
+        ...     parent_elm.append(child_elm)
+        ...     loader.idcache_index(child_elm)
 
         If you intend to reserve a UUID that should be inserted later,
         use :meth:`generate_uuid()` directly.

src/capellambse/model/_descriptors.py

@@ -350,8 +350,16 @@ class Single(Accessor[T_co | None], t.Generic[T_co]):
 
     Examples
     --------
-    >>> class Foo(capellacore.CapellaElement):
-    ...     bar = Single["Bar"](Containment("bar", (NS, "Bar")))
+    This example creates two classes Foo and Bar, where Bar may contain
+    a single Foo object:
+
+    >>> import capellambse.model as m
+    >>> from capellambse.metamodel import capellacore
+    >>> TEST_NS = m.Namespace(m.VIRTUAL_NAMESPACE_PREFIX + "/test", "test")
+    >>>
+    >>> class Foo(capellacore.CapellaElement, ns=TEST_NS): ...
+    >>> class Bar(capellacore.CapellaElement, ns=TEST_NS):
+    ...     foo = Single["Foo"](Containment("ownedFoo", (TEST_NS, "Foo")))
     """
 
     def __init__(

src/capellambse/model/_model.py

@@ -383,9 +383,17 @@ class as the superclass of every concrete model element
         return a list of every Logical Component in the model:
 
         >>> model.search("LogicalComponent")
+        [0] <LogicalComponent 'Hogwarts' (0d2edb8f-fa34-4e73-89ec-fb9a63001440)>
+        ...
         >>> model.search("org.polarsys.capella.core.data.la:LogicalComponent")
+        [0] <LogicalComponent 'Hogwarts' (0d2edb8f-fa34-4e73-89ec-fb9a63001440)>
+        ...
         >>> model.search( (capellambse.metamodel.la.NS, "LogicalComponent") )
+        [0] <LogicalComponent 'Hogwarts' (0d2edb8f-fa34-4e73-89ec-fb9a63001440)>
+        ...
         >>> model.search( ("org.polarsys.capella.core.data.la", "LogicalComponent") )
+        [0] <LogicalComponent 'Hogwarts' (0d2edb8f-fa34-4e73-89ec-fb9a63001440)>
+        ...
         """
         classes: set[type[_obj.ModelObject]] = set()
         for clsname in clsnames:
@@ -628,18 +636,18 @@ def update_diagram_cache(
         Passing a bare filename looks up the executable in the PATH,
         after replacing a possible '{VERSION}' field:
 
-        >>> model.update_diagram_cache("capella", "png")
-        >>> model.update_diagram_cache("capella{VERSION}", "png")
+        >>> model.update_diagram_cache("capella", "png")                        # doctest: +SKIP
+        >>> model.update_diagram_cache("capella{VERSION}", "png")               # doctest: +SKIP
 
         Passing an absolute path to a local installation of Capella that
         contains the Capella version will use that executable:
 
-        >>> model.update_diagram_cache("/opt/capella{VERSION}/capella", "png")
+        >>> model.update_diagram_cache("/opt/capella{VERSION}/capella", "png")  # doctest: +SKIP
 
         Passing a docker image name will launch a docker container, using the
         Capella binary at the image's ENTRYPOINT:
 
-        >>> model.update_diagram_cache(
+        >>> model.update_diagram_cache(                                         # doctest: +SKIP
         ...     "ghcr.io/dsd-dbs/capella-dockerimages/capella/base:{VERSION}-selected-dropins-main",
         ...     "png",
         ... )