Documentation cleanup

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.
+    - 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.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 dimension for its properties that
+are referred to by the property shapes.
+
+Arguments:
+    name: Name that of dimension.
+    description: Description of the dimension.
+
+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 defines the instances
+of the metadata.
+
+Arguments:
+    name: Name of the property.
+    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 an 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.

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(

doc/CMakeLists.txt

@@ -33,9 +33,10 @@ set(DOXYGEN_DOXYFILE_OUT "${BINARY_BUILD_DIR}/Doxyfile")
 set(DOXYGEN_INDEX_FILE ${DOXYGEN_OUTPUT_XML_DIR}/index.xml)
 
 configure_file(
-    "${CMAKE_CURRENT_SOURCE_DIR}/conf.py.in"
-    "${BINARY_BUILD_DIR}/conf.py"
-    @ONLY)
+  "${CMAKE_CURRENT_SOURCE_DIR}/conf.py.in"
+  "${BINARY_BUILD_DIR}/conf.py"
+  @ONLY
+)
 
 file(COPY
   "${CMAKE_SOURCE_DIR}/LICENSE"
@@ -48,24 +49,28 @@ file(COPY
   "${CMAKE_CURRENT_SOURCE_DIR}/contributors_guide"
   "${CMAKE_CURRENT_SOURCE_DIR}/getting_started"
   "${CMAKE_CURRENT_SOURCE_DIR}/user_guide"
-  DESTINATION
-  "${BINARY_BUILD_DIR}"
+  DESTINATION "${BINARY_BUILD_DIR}"
 )
 
 configure_file(
-    ${DOXYGEN_DOXYFILE_IN}
-    ${DOXYGEN_DOXYFILE_OUT}
-    @ONLY)
+  ${DOXYGEN_DOXYFILE_IN}
+  ${DOXYGEN_DOXYFILE_OUT}
+  @ONLY
+)
 
 
 # Doxygen command
-add_custom_command(OUTPUT ${DOXYGEN_INDEX_FILE}
-                   DEPENDS ${DLITE_PUBLIC_HEADERS}
-                   COMMAND ${DOXYGEN_EXECUTABLE} ${DOXYFILE_OUT}
-                   MAIN_DEPENDENCY ${DOXYFILE_OUT}
-		   WORKING_DIRECTORY ${BINARY_BUILD_DIR}
-                   COMMENT "Generating docs"
-                   VERBATIM)
+add_custom_command(
+  OUTPUT ${DOXYGEN_INDEX_FILE}
+  COMMAND ${DOXYGEN_EXECUTABLE} ${DOXYFILE_OUT}
+  MAIN_DEPENDENCY ${DOXYGEN_DOXYFILE_OUT}
+  DEPENDS
+    ${DLITE_PUBLIC_HEADERS}
+    dlitepy
+  WORKING_DIRECTORY ${BINARY_BUILD_DIR}
+  COMMENT "Generating docs"
+  VERBATIM
+)
 
 # Named constom target
 add_custom_target(Doxygen ALL DEPENDS ${DOXYGEN_INDEX_FILE})
@@ -74,15 +79,16 @@ add_custom_target(Doxygen ALL DEPENDS ${DOXYGEN_INDEX_FILE})
 add_custom_command(OUTPUT ${SPHINX_INDEX_FILE}
   COMMAND
   ${SPHINX_EXECUTABLE}
-        -q -b html
-        -c "${BINARY_BUILD_DIR}"
-        -d "${SPHINX_CACHE_DIR}"
-        ${BINARY_BUILD_DIR}
-        "${SPHINX_HTML_DIR}"
+    -q -b html
+    -c "${BINARY_BUILD_DIR}"
+    -d "${SPHINX_CACHE_DIR}"
+    ${BINARY_BUILD_DIR}
+    "${SPHINX_HTML_DIR}"
   DEPENDS
-  ${DOXYGEN_INDEX_FILE}
-  ${BINARY_BUILD_DIR}/respirator.py
+    ${DOXYGEN_INDEX_FILE}
+    ${BINARY_BUILD_DIR}/respirator.py
   MAIN_DEPENDENCY ${BINARY_BUILD_DIR}/conf.py
-  COMMENT "Building HTML documentation with Sphinx")
+  COMMENT "Building HTML documentation with Sphinx"
+)
 
 add_custom_target(Sphinx ALL DEPENDS ${SPHINX_INDEX_FILE})

doc/getting_started/tutorial.md

@@ -190,7 +190,34 @@ Both dimensions and properties can also be provided as arrays using a `dict` wit
             "shape": ["N"],
             "description": "Maximum Power"
         },
-        ...
+        {
+            "name": "impp",
+            "type": "float64",
+            "unit": "A",
+            "shape": ["N"],
+            "description": "Maximum power point current."
+        },
+        {
+            "name": "isc",
+            "type": "float64",
+            "unit": "A",
+            "shape": ["N"],
+            "description": "Short circuit current."
+        },
+        {
+            "name": "vmpp",
+            "type": "float64",
+            "unit": "V",
+            "shape": ["N"],
+            "description": "Maximum power point voltage."
+        },
+        {
+            "name": "voc",
+            "type": "float64",
+            "unit": "V",
+            "shape": ["N"],
+            "description": "Open circuit voltage."
+        }
     ]
 }
 ```