Skip to content

Commit

Permalink
Fix documentation warnings and errors (#994)
Browse files Browse the repository at this point in the history
Fix most warnings and errors from doxygen and sphinx.

Improved generated documentation.

---------

Co-authored-by: Francesca L. Bleken <48128015+francescalb@users.noreply.github.com>
  • Loading branch information
jesper-friis and francescalb authored Oct 30, 2024
1 parent dde498f commit 62c26ee
Show file tree
Hide file tree
Showing 40 changed files with 479 additions and 277 deletions.
19 changes: 12 additions & 7 deletions bindings/python/dlite-collection-python.i
Original file line number Diff line number Diff line change
Expand Up @@ -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."""
Expand Down
76 changes: 55 additions & 21 deletions bindings/python/dlite-entity-python.i
Original file line number Diff line number Diff line change
Expand Up @@ -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."""
Expand Down Expand Up @@ -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):
Expand Down Expand Up @@ -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):
Expand Down
105 changes: 73 additions & 32 deletions bindings/python/dlite-entity.i
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand All @@ -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 {
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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)};
Expand Down
4 changes: 4 additions & 0 deletions bindings/python/dlite-misc-python.i
Original file line number Diff line number Diff line change
Expand Up @@ -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())]
Expand Down Expand Up @@ -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()
Expand Down
1 change: 1 addition & 0 deletions bindings/python/dlite-python.i
Original file line number Diff line number Diff line change
Expand Up @@ -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(
Expand Down
1 change: 1 addition & 0 deletions bindings/python/python-protocol-plugins/file.py
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
18 changes: 10 additions & 8 deletions bindings/python/python-protocol-plugins/sftp.py
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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")
Expand Down
Loading

0 comments on commit 62c26ee

Please sign in to comment.