Fix documentation warnings and errors (#994)

Fix most warnings and errors from doxygen and sphinx.

Improved generated documentation.

---------

Co-authored-by: Francesca L. Bleken <[email protected]>

bindings/python/dlite-collection-python.i

@@ -56,19 +56,24 @@ class Collection(Instance):
     to it.  Likewise, the len() of a collection will return the number
     of instances.
 
-    Use the get_relations() method (or the convenience methods
-    get_subjects(), get_predicates() and get_objects()) to iterate
+    Use the `get_relations()` method (or the convenience methods
+    `get_subjects()`, `get_predicates()` and `get_objects()`) to iterate
     over relations.  The number of relations is available via the
     `nrelations` property.
 
-    Relations are (s, p, o, d=None)-triples with an optional fourth field
+    Relations are `(s, p, o, d=None)`-triples with an optional fourth field
     `d`, specifying the datatype of the object.  The datatype may have the
     following values:
 
-      - None: object is an IRI.
-      - Starts with '@': object is a language-tagged plain literal.
-        The language identifier follows the '@'-sign.
-      - Otherwise: object is a literal with datatype `d`.
+    - None: object is an IRI.
+    - Starts with '@': object is a language-tagged plain literal.
+      The language identifier follows the '@'-sign. e.g. `@en`
+    - Otherwise: object is a literal with datatype `d`.
+
+    Arguments:
+        id: URI or UUID of the new instance.  The default is to create a
+            collection with no URI and random (version 4) UUID.
+
     """
     def __new__(cls, id=None):
         """Creates an empty collection."""

bindings/python/dlite-entity-python.i

@@ -86,11 +86,11 @@ class Metadata(Instance):
         return inst
 
     # For convenience. Easier to use than self.properties["properties"]
-    props = property(
-        fget=lambda self: {p.name: p for p in self.properties["properties"]},
-        doc="A dict mapping property name to the `Property` object for the "
-        "described metadata.",
-    )
+    @property
+    def props(self):
+        """A dict mapping property name to the `Property` object for the
+        described metadata."""
+        return {p.name: p for p in self.properties["properties"]}
 
     def getprop(self, name):
         """Returns the metadata property object with the given name."""
@@ -248,9 +248,24 @@ def get_instance(
                 '' if self.unit is None else self.unit,
                 '' if self.description is None else self.description)
 
-    type = property(get_type, doc='Type name.')
-    dtype = property(get_dtype, doc='Type number.')
-    shape = property(get_shape, set_shape, doc='Array of dimension indices.')
+    @property
+    def type(self):
+        """Type name."""
+        return self.get_type()
+
+    @property
+    def dtype(self):
+        """Type number."""
+        return self.get_dtype()
+
+    @property
+    def shape(self):
+        """Array of dimension indices."""
+        return self.get_shape()
+
+    @shape.setter
+    def shape(self, value):
+        return self.set_shape(value)
 
     # Too be removed...
     def _get_dims_depr(self):
@@ -376,19 +391,38 @@ def get_instance(
             f'"{self.uri if self.uri else self.meta.uri}"'
         )
 
-    meta = property(get_meta, doc="Reference to the metadata of this instance.")
-    dimensions = property(
-        lambda self: dict((d.name, int(v))
-                          for d, v in zip(self.meta['dimensions'],
-                                          self.get_dimensions())),
-        doc='Dictionary with dimensions name-value pairs.')
-    properties = property(lambda self:
-        {p.name: self[p.name] for p in self.meta['properties']},
-        doc='Dictionary with property name-value pairs.')
-    is_data = property(_is_data, doc='Whether this is a data instance.')
-    is_meta = property(_is_meta, doc='Whether this is a metadata instance.')
-    is_metameta = property(_is_metameta,
-                           doc='Whether this is a meta-metadata instance.')
+    @property
+    def meta(self):
+        """Reference to the metadata of this instance."""
+        return self.get_meta()
+
+    @property
+    def dimensions(self):
+        """Dictionary with dimensions name-value pairs."""
+        return dict(
+            (d.name, int(v))
+            for d, v in zip(self.meta['dimensions'], self.get_dimensions())
+        )
+
+    @property
+    def properties(self):
+        """Dictionary with property name-value pairs."""
+        return {p.name: self[p.name] for p in self.meta['properties']}
+
+    @property
+    def is_data(self):
+        """Whether this is a data instance."""
+        return self._is_data()
+
+    @property
+    def is_meta(self):
+        """Whether this is a metadata instance."""
+        return self._is_meta()
+
+    @property
+    def is_metameta(self):
+        """Whether this is a meta-metadata instance."""
+        return self._is_metameta()
 
     @classmethod
     def from_metaid(cls, metaid, dimensions, id=None):

bindings/python/dlite-entity.i

@@ -93,10 +93,23 @@ char** dlite_swig_istore_get_uuids()
 %}
 
 
-
 /* ---------
  * Dimension
  * --------- */
+%feature("docstring", "\
+A dimension represented by its name and description.
+Metadata can define a set of common dimensions for its properties that
+are referred to by the shape of each property.
+
+Arguments:
+    name: Dimension name.
+    description: Dimension description.
+
+Attributes:
+    name: Dimension name.
+    description: Dimension description.
+
+") _DLiteDimension;
 %rename(Dimension) _DLiteDimension;
 struct _DLiteDimension {
   char *name;
@@ -123,7 +136,31 @@ struct _DLiteDimension {
  * Property
  * -------- */
 %feature("docstring", "\
-Creates a new property with the provided attributes.
+Represents a property.
+All metadata must have one or more properties that define the instances
+of the metadata.
+
+Arguments:
+    name: Property name.
+    type: Property type. Ex: 'int', 'blob14', 'float64', 'ref'...
+    ref: Optional. URL to metadata. Only needed for `type='ref'`.
+    shape: Optional. Specifies the dimensionality of property.  If `shape`
+        is not given, the property is a scalar (dimensionality zero).
+        It should be a sequence of dimension names.
+    unit: Optional. The unit for properties with a unit. The unit should
+         be a valid unit label defined by EMMO or a custom ontology.
+    description: Optional: A human description of the property.
+
+Attributes:
+    name: Property name.
+    size: Number of bytes needed to represent a single instance of `type`
+        in memory.
+    ref: Value of the `ref` argument.
+    ndims: Number of dimensions of the property. A scalar has `ndims=0`.
+    unit: The unit of the property.
+    description: Property description.
+    dims: Deprecated alias for shape.
+
 ") _DLiteProperty;
 %rename(Property) _DLiteProperty;
 struct _DLiteProperty {
@@ -193,18 +230,20 @@ struct _DLiteProperty {
  * Relation
  * -------- */
 %feature("docstring", "\
-Relations in DLite corresponds to RDF-triples, but are internally 4 fields:
-  - s: subject
-  - p: predicate
-  - o: object
-  - d: datatype
-
-The datatype is the datatype for literal objects. It may have three forms:
-  - None: object is an IRI (rdfs:Resource).
-  - Starts with '@': object is a language-tagged plain literal
-    (rdf:langString). The language identifier follows the '@'-sign.
-    Ex: '@en' for english.
-  - Otherwise: object is a literal with datatype `d`. Ex: 'xsd:int'.
+A DLite relation representing an RDF triple.
+
+Arguments:
+    s: Subject IRI.
+    p: Predicate IRI.
+    o: Either an IRI for non-literal objects or the literal value for
+        literal objects.
+    d: The datatype IRI for literal objects.  It may have three forms:
+
+        - None: object is an IRI (rdfs:Resource).
+        - Starts with '@': object is a language-tagged plain literal
+          (rdf:langString). The language identifier follows the '@'-sign.
+          Ex: '@en' for english.
+        - Otherwise: object is a literal with datatype `d`. Ex: 'xsd:int'.
 
 As an internal implementation detail, relations also have an `id` field.
 It may change in the future, so please don't rely on it.
@@ -244,24 +283,26 @@ struct _Triple {
  * Instance
  * -------- */
 %feature("docstring", "\
-Returns a new instance.
-
-Instance(metaid=None, dims=None, id=None, url=None, storage=None, driver=None,
-         location=None, options=None, dimensions=None, properties=None,
-         description=None)
-
-    Is called from one of the following class methods defined in dlite.py:
-
-      - from_metaid(cls, metaid, dimensions, id=None)
-      - from_url(cls, url, metaid=None)
-      - from_storage(cls, storage, id=None, metaid=None)
-      - from_location(cls, driver, location, options=None, id=None)
-      - from_json(cls, jsoninput, id=None, metaid=None)
-      - from_bson(cls, bsoninput)
-      - from_dict(cls, d, id=None, single=None, check_storages=True)
-      - create_metadata(cls, uri, dimensions, properties, description)
-
-      For details, see the documentation for the class methods.
+Represents a DLite instance.
+
+This is the most central class in DLite.  It has a complex `__init__()`
+method and is intended to be instantiated with one of the following class
+methods:
+
+- from_metaid(cls, metaid, dimensions, id=None)
+- from_url(cls, url, metaid=None)
+- from_storage(cls, storage, id=None, metaid=None)
+- from_location(cls, driver, location, options=None, id=None)
+- from_json(cls, jsoninput, id=None, metaid=None)
+- from_bson(cls, bsoninput)
+- from_dict(cls, d, id=None, single=None, check_storages=True)
+- create_metadata(cls, uri, dimensions, properties, description)
+
+For details, see the documentation of the individual class methods.
+
+Attributes:
+    uuid: The UUID of the instance.
+    uri: The URI of the instance.
 
 ") _DLiteInstance;
 %apply(int *IN_ARRAY1, int DIM1) {(int *dims, int ndims)};

bindings/python/dlite-misc-python.i

@@ -32,6 +32,9 @@ class errctl():
             - "<stderr>": Write errors to stderr (default).
             - "<stdout>": Write errors to stdout.
 
+    Attributes:
+        filename: Filename to redirect errors to.
+
     """
     def __init__(self, hide=(), show=(), filename="<stderr>"):
         allcodes = [-i for i in range(1, _dlite._get_number_of_errors())]
@@ -79,6 +82,7 @@ class errctl():
 
 
 silent = errctl(filename="None")
+"""Context manager for a silent code block.  Same as `errctl(filename="None")`."""
 
 # A set for keeping track of already issued deprecation warnings
 _deprecation_warning_record = set()

bindings/python/dlite-python.i

@@ -1477,6 +1477,7 @@ def instance_cast(inst, newtype=None):
 
 # Deprecated exceptions
 class DLiteSearchError(_dlite.DLiteLookupError):
+    """Deprecated.  Has been renamed to DLiteLookupError."""
     def __init__(self, *args, **kwargs):
         super().__init__(*args, **kwargs)
         deprecation_warning(

bindings/python/python-protocol-plugins/file.py

@@ -17,6 +17,7 @@ def open(self, location, options=None):
         Arguments:
             location: A URL or path to a file or directory.
             options: Supported options:
+
                 - `mode`: Combination of "r" (read), "w" (write) or "a" (append)
                   Defaults to "r" if `location` exists and "w" otherwise.
                   This default avoids accidentially overwriting an existing

bindings/python/python-protocol-plugins/sftp.py

@@ -27,6 +27,7 @@ def open(self, location, options=None):
                 qualified as `username:password@host:port`.  In the latter
                 case the port/username/password takes precedence over `options`.
             options: Supported options:
+
                 - `username`: User name.
                 - `password`: Password.
                 - `hostname`: Host name.
@@ -47,14 +48,15 @@ def open(self, location, options=None):
                   For compresison "bzip2"; 1 to 9 are valid.
 
         Example:
-
-            # For key-based authorisation, you may get the `key_type` and
-            # `key_bytes` arguments as follows:
-            pkey = paramiko.Ed25519Key.from_private_key_file(
-                "/home/john/.ssh/id_ed25519"
-            )
-            key_type = pkey.name
-            key_bytes = pkey.asbytes().hex()
+            Here is an example of how you can use a private ssh-key
+
+                >>> # For key-based authorisation, you may get the `key_type`
+                >>> # and `key_bytes` arguments as follows:
+                >>> pkey = paramiko.Ed25519Key.from_private_key_file(
+                ...     "/home/john/.ssh/id_ed25519"
+                ... )
+                >>> key_type = pkey.name
+                >>> key_bytes = pkey.asbytes().hex()
 
         """
         options = Options(options, "port=22;compression=lzma")