aas.util: Rework docstrings for sphinx

aas/util/identification.py

@@ -6,12 +6,13 @@
 #
 # SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
 """
-This module generates identifiers.
+This module generates :class:`Identifiers <aas.model.base.Identifier>`.
 
-Generate [identifier]:  -> Try:
-Abstract                -> AbstractIdentifierGenerator
-UUID                    -> UUIDGenerator
-IRI                     -> NamespaceIRIGenerator
+To Generate [identifier]:  -> Try:
+
+- Abstract                -> :class:`~.AbstractIdentifierGenerator`
+- UUID                    -> :class:`~.UUIDGenerator`
+- IRI                     -> :class:`NamespaceIRIGenerator`
 """
 
 import abc
@@ -24,7 +25,8 @@ from .. import model
 
 class AbstractIdentifierGenerator(metaclass=abc.ABCMeta):
     """
-    Abstract base class for identifier generators that generate identifiers based on an internal schema and an
+    Abstract base class for identifier generators that generate :class:`Identifiers <aas.model.base.Identifier>` based
+    on an internal schema and an
     (optional) proposal.
 
     Different Implementations of IdentifierGenerators may generate differently formed ids, e.g. URNs, HTTP-scheme IRIs,
@@ -61,9 +63,15 @@ class NamespaceIRIGenerator(AbstractIdentifierGenerator):
     """
     An IdentifierGenerator, that generates IRIs in a given namespace, checking uniqueness against a Registry.
 
-    Identifiers are generated by concatenating a fixed namespace with the proposed suffix. To verify uniqueness, the
-    existence of the identification is checked by querying the given Registry. If a collision is detected, a number
-    is prepended
+    :class:`Identifiers <aas.model.base.Identifier>` are generated by concatenating a fixed namespace with the proposed
+    suffix. To verify uniqueness, the
+    existence of the identification is checked by querying the given Registry. If a collision
+    is detected, a number is prepended
+
+    :ivar namespace: The IRI Namespace to generate Identifications in. It must be a valid IRI (starting with a
+                     scheme) and end on either #, /, or = to form a reasonable namespace.
+    :ivar ~.provider: An :class:`~aas.model.provider.AbstractObjectProvider` to check existence of
+        :class:`Identifiers <aas.model.base.Identifier>`
     """
     def __init__(self, namespace: str, provider: model.AbstractObjectProvider):
         """

aas/util/traversal.py

@@ -17,9 +17,12 @@ from .. import model
 def walk_submodel(collection: Union[model.Submodel, model.SubmodelElementCollection]) \
         -> Iterator[model.SubmodelElement]:
     """
-    Traverse the SubmodelElements in a Submodel or a SubmodelElementCollection recursively in post-order tree-traversal.
+    Traverse the :class:`SubmodelElements <aas.model.submodel.SubmodelElement>` in a
+    :class:`~aas.model.submodel.Submodel` or a :class:`~aas.model.submodel.SubmodelElementCollection` recursively in
+    post-order tree-traversal.
 
-    This is a generator function, yielding all the SubmodelElements. No SubmodelElements should be added, removed or
+    This is a generator function, yielding all the :class:`SubmodelElements <aas.model.submodel.SubmodelElement>`. No
+    :class:`SubmodelElements <aas.model.submodel.SubmodelElement>` should be added, removed or
     moved while iterating, as this could result in undefined behaviour.
     """
     elements = collection.submodel_element if isinstance(collection, model.Submodel) else collection.value