From 75c108c7f988af5c55bebd885272553ce842428c Mon Sep 17 00:00:00 2001 From: Jesper Friis Date: Mon, 28 Oct 2024 22:40:08 +0100 Subject: [PATCH] Documentation cleanup --- bindings/python/dlite-collection-python.i | 19 ++++--- bindings/python/dlite-entity.i | 67 ++++++++++++++++++----- bindings/python/dlite-misc-python.i | 4 ++ bindings/python/dlite-python.i | 1 + doc/CMakeLists.txt | 52 ++++++++++-------- doc/getting_started/tutorial.md | 29 +++++++++- 6 files changed, 127 insertions(+), 45 deletions(-) diff --git a/bindings/python/dlite-collection-python.i b/bindings/python/dlite-collection-python.i index 2a28c9e55..91bb23150 100644 --- a/bindings/python/dlite-collection-python.i +++ b/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.""" diff --git a/bindings/python/dlite-entity.i b/bindings/python/dlite-entity.i index b5dc7447c..879f63da6 100644 --- a/bindings/python/dlite-entity.i +++ b/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. diff --git a/bindings/python/dlite-misc-python.i b/bindings/python/dlite-misc-python.i index 544989b0c..5de269502 100644 --- a/bindings/python/dlite-misc-python.i +++ b/bindings/python/dlite-misc-python.i @@ -32,6 +32,9 @@ class errctl(): - "": Write errors to stderr (default). - "": Write errors to stdout. + Attributes: + filename: Filename to redirect errors to. + """ def __init__(self, hide=(), show=(), filename=""): 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() diff --git a/bindings/python/dlite-python.i b/bindings/python/dlite-python.i index f0fa88e32..38870a21c 100644 --- a/bindings/python/dlite-python.i +++ b/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( diff --git a/doc/CMakeLists.txt b/doc/CMakeLists.txt index f93ec7c21..5be55188b 100644 --- a/doc/CMakeLists.txt +++ b/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}) diff --git a/doc/getting_started/tutorial.md b/doc/getting_started/tutorial.md index fe53bde32..2570c8029 100644 --- a/doc/getting_started/tutorial.md +++ b/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." + } ] } ```