Automating docs and fixing some images

caterva2/client.py

@@ -656,27 +656,39 @@ def __repr__(self):
 
     @property
     def dtype(self):
+        """
+        The data type of the dataset.
+        """
         try:
             return self.meta["dtype"]
         except KeyError as e:
             raise AttributeError("'Dataset' object has no attribute 'dtype'.") from e
 
     @property
     def shape(self):
+        """
+        The shape of the dataset.
+        """
         try:
             return tuple(self.meta["shape"])
         except KeyError as e:
             raise AttributeError("'Dataset' object has no attribute 'shape'.") from e
 
     @property
     def chunks(self):
+        """
+        The chunkshape of the compressed dataset.
+        """
         try:
             return tuple(self.meta["chunks"])
         except KeyError as e:
             raise AttributeError("'Dataset' object has no attribute 'chunks'.") from e
 
     @property
     def blocks(self):
+        """
+        The blockshape of the compressed dataset.
+        """
         try:
             return tuple(self.meta["blocks"])
         except KeyError as e:
@@ -1351,6 +1363,37 @@ def copy(self, src, dst):
         return pathlib.PurePosixPath(result)
 
     def concatenate(self, srcs, dst, axis):
+        """
+        Concatenate the srcs along axis to a new location dst.
+
+        Parameters
+        ----------
+        srcs: list of Paths
+            Source files to be concatenated
+        dst : Path
+            The destination path for the file.
+        axis: int
+            Axis along which to concatenate.
+
+        Returns
+        -------
+        Path
+            The new path of the concatenated file.
+
+        Examples
+        --------
+        >>> import caterva2 as cat2
+        >>> import numpy as np
+        >>> # For concatenating a file you need to be a registered user
+        >>> client = cat2.Client("https://cat2.cloud/demo", ("joedoe@example.com", "foobar"))
+        >>> root = client.get('@personal')
+        >>> root.upload('root-example/dir2/ds-4d.b2nd', "a.b2nd")
+        <Dataset: @personal/a.b2nd>
+        >>> root.upload('root-example/dir2/ds-4d.b2nd', "b.b2nd")
+        <Dataset: @personal/b.b2nd>
+        >>> client.concatenate(['@personal/a.b2nd', '@personal/b.b2nd'], '@personal/c.b2nd', axis=0)
+        PurePosixPath('@personal/c.b2nd')
+        """
         urlbase, _ = _format_paths(self.urlbase)
         result = api_utils.post(
             f"{self.urlbase}/api/concat/",
@@ -1361,6 +1404,37 @@ def concatenate(self, srcs, dst, axis):
         return pathlib.PurePosixPath(result)
 
     def stack(self, srcs, dst, axis):
+        """
+        Stack the files in srcs along new axis to a new location dst.
+
+        Parameters
+        ----------
+        srcs: list of Paths
+            Source files accessible by client to be stacked
+        dst : Path
+            The destination path for the file.
+        axis: int
+            Axis along which to stack.
+
+        Returns
+        -------
+        Path
+            The new path of the stacked file.
+
+        Examples
+        --------
+        >>> import caterva2 as cat2
+        >>> import numpy as np
+        >>> # For stacking a file you need to be a registered user
+        >>> client = cat2.Client("https://cat2.cloud/demo", ("joedoe@example.com", "foobar"))
+        >>> root = client.get('@personal')
+        >>> root.upload('root-example/dir2/ds-4d.b2nd', "a.b2nd")
+        <Dataset: @personal/a.b2nd>
+        >>> root.upload('root-example/dir2/ds-4d.b2nd', "b.b2nd")
+        <Dataset: @personal/b.b2nd>
+        >>> client.stack(['@personal/a.b2nd', '@personal/b.b2nd'], '@personal/c.b2nd', axis=0)
+        PurePosixPath('@personal/c.b2nd')
+        """
         urlbase, _ = _format_paths(self.urlbase)
         result = api_utils.post(
             f"{self.urlbase}/api/stack/",

doc/conf.py

@@ -6,10 +6,10 @@
 # -- Project information -----------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 
-project = 'Caterva2'
-copyright = '2024, ironArray SLU'
-author = 'ironArray SLU'
-release = '0.3.dev0'
+project = "Caterva2"
+copyright = "2024, ironArray SLU"
+author = "ironArray SLU"
+release = "0.3.dev0"
 
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
@@ -26,19 +26,20 @@
     "nbsphinx",
 ]
 
+autosummary_generate = True  # Enable auto generation of stub files
+
 myst_enable_extensions = [
     "html_image",
 ]
 
-templates_path = ['_templates']
-exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
-
+templates_path = ["_templates"]
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
 
 
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 
-html_static_path = ['_static']
+html_static_path = ["_static"]
 source_suffix = [".rst", ".md"]
 html_theme = "pydata_sphinx_theme"
 html_css_files = [

doc/reference/client_class.rst

@@ -8,67 +8,59 @@ A client is a remote repository that can be subscribed to. It is the main entry
 .. currentmodule:: caterva2
 
 
-Constructor
------------
-
-.. autosummary::
-    :toctree: autofiles
-
-    Client.__init__
-
-
-Getting roots, files, datasets, subscribing...
-----------------------------------------------
-
-.. autosummary::
-    :toctree: autofiles
-
-    Client.get
-    Client.get_roots
-    Client.get_list
-    Client.subscribe
-
-
-Fetch / download / upload datasets
-----------------------------------
-
-.. autosummary::
-    :toctree: autofiles
-
-    Client.fetch
-    Client.get_chunk
-    Client.download
-    Client.upload
-
-
-User management
----------------
-
-.. autosummary::
-    :toctree: autofiles
-
-    Client.adduser
-    Client.deluser
-    Client.listusers
-
-
-Utility methods
----------------
-
-.. autosummary::
-    :toctree: autofiles
-
-    Client.append
-    Client.copy
-    Client.move
-    Client.remove
-    Client.get_info
-
-
-Evaluating expressions
-----------------------
-
-.. autosummary::
-    :toctree: autofiles
-
-    Client.lazyexpr
+.. autoclass:: Client
+    :members:
+    :exclude-members: get, get_roots, get_list, subscribe, fetch, get_chunk, download, upload, adduser, deluser, listusers, lazyexpr
+
+    :Special Methods:
+    .. autosummary::
+
+       __init__
+       get
+       get_roots
+       get_list
+       subscribe
+       fetch
+       get_chunk
+       download
+       upload
+       adduser
+       deluser
+       listusers
+       lazyexpr
+
+
+    Constructor
+    ----------
+    .. automethod:: __init__
+
+
+    Getting roots, files, datasets, subscribing...
+    ----------------------------------------------
+    .. automethod:: get
+    .. automethod:: get_roots
+    .. automethod:: get_list
+    .. automethod:: subscribe
+
+
+    Fetch / download / upload datasets
+    ----------------------------------
+    .. automethod:: fetch
+    .. automethod:: get_chunk
+    .. automethod:: download
+    .. automethod:: upload
+
+
+    User management
+    ---------------
+    .. automethod:: adduser
+    .. automethod:: deluser
+    .. automethod:: listusers
+
+
+    Evaluating expressions
+    ----------------------
+    .. automethod:: lazyexpr
+
+    Utility methods
+    ---------------

doc/reference/dataset_class.rst

@@ -5,31 +5,25 @@ Dataset class
 
 A dataset is a Blosc2-encoded file on a root repository (thus a :ref:`File <ref-API-File>`) representing either a flat string of bytes or an n-dimensional array.
 
-.. currentmodule:: caterva2.client.Dataset
 
+.. currentmodule:: caterva2
 
-Methods
--------
+.. autoclass:: Dataset
+    :members:
+    :inherited-members:
+    :exclude-members: client, urlbase, cookie
+    :show-inheritance:
+    :member-order: groupwise
 
-.. autosummary::
-    :toctree: autofiles
-    :nosignatures:
+    :Special Methods:
+    .. autosummary::
+        __init__
+        __getitem__
 
-    __init__
-    __getitem__
-    slice
-    append
-    get_download_url
-    download
-    vlmeta
+    Constructor
+    -----------
+    .. automethod:: __init__
 
-Attributes
-----------
-
-.. autosummary::
-    :toctree: autofiles
-
-    shape
-    chunks
-    blocks
-    dtype
+    Utility Methods
+    -----------
+    .. automethod:: __getitem__

doc/reference/file_class.rst

@@ -6,14 +6,21 @@ File class
 A file is either a Blosc2 dataset or a regular file on a root repository.
 
 .. currentmodule:: caterva2
-.. autosummary::
-    :toctree: autofiles
 
-    File.__init__
-    File.__getitem__
-    File.get_download_url
-    File.download
-    File.remove
-    File.move
-    File.copy
-    File.vlmeta
+.. autoclass:: File
+    :members:
+    :exclude-members: client, urlbase, cookie
+    :member-order: groupwise
+
+    :Special Methods:
+    .. autosummary::
+        __init__
+        __getitem__
+
+    Constructor
+    -----------
+    .. automethod:: __init__
+
+    Utility Methods
+    -----------
+    .. automethod:: __getitem__

doc/reference/index.rst

@@ -1,8 +1,7 @@
 API Reference
 =============
-
 .. toctree::
-    :maxdepth: 2
+    :maxdepth: 1
 
     client_class
     root_class