Enhanced documentation including docstrings

Author: forman

CHANGES.md

@@ -1,4 +1,9 @@
-## Version 0.2.0 (2024-18-01)
+## Version 0.2.1 (in development)
+
+* Enhanced documentation including docstrings of several Python API objects.
+
+
+## Version 0.2.0 (from 2024-18-01)
 
 ### Enhancements
 

README.md

@@ -16,7 +16,8 @@ packages [xarray](https://docs.xarray.dev/) and [zarr](https://zarr.readthedocs.
 
 The objective of `zappend` is to address recurring memory issues when generating large 
 geospatial datacubes using the [Zarr format](https://zarr.readthedocs.io/) 
-by subsequently concatenating data slices along an append dimension, usually `time`. 
+by subsequently concatenating data slices along an append dimension, e.g., `time` 
+(the default) for geospatial satellite observations. 
 Each append step is atomic, that is, the append operation is a transaction that can be 
 rolled back, in case the append operation fails. This ensures integrity of the target 
 data cube. 

docs/index.md

@@ -10,7 +10,8 @@ packages [xarray](https://docs.xarray.dev/) and [zarr](https://zarr.readthedocs.
 
 The objective of `zappend` is to address recurring memory issues when generating large 
 geospatial datacubes using the [Zarr format](https://zarr.readthedocs.io/) 
-by subsequently concatenating data slices along an append dimension, usually `time`. 
+by subsequently concatenating data slices along an append dimension, e.g., `time` 
+(the default) for geospatial satellite observations.  
 Each append step is atomic, that is, the append operation is a transaction that can be 
 rolled back, in case the append operation fails. This ensures integrity of the target 
 data cube. 

zappend/api.py

@@ -38,6 +38,13 @@ def zappend(
     """
     Robustly create or update a Zarr dataset from dataset slices.
 
+    It concatenates the dataset slices from given `slices` along a given append
+    dimension, e.g., `"time"` (the default) for geospatial satellite observations.
+    Each append step is atomic, that is, the append operation is a transaction
+    that can be rolled back, in case the append operation fails.
+    This ensures integrity of the  target data cube `target_dir` given in `config`
+    or `kwargs`.
+
     Args:
         slices: An iterable that yields slice objects. A slice object is
             either a ``str``, ``xarray.Dataset``, ``SliceSource`` or a factory

zappend/cli.py

@@ -41,7 +41,14 @@ def zappend(
     dry_run: bool,
     help_config: str | None,
 ):
-    """Create or update a Zarr datacube TARGET from slice datasets SLICES."""
+    """Create or update a Zarr datacube TARGET from slice datasets SLICES.
+
+    It concatenates the dataset SLICES along a given append dimension, e.g., `"time"`
+    (the default) for geospatial satellite observations. Each append step is atomic,
+    that is, the append operation is a transaction that can be rolled back, in case
+    the append operation fails. This ensures integrity of the target data cube given
+    by TARGET or in CONFIG.
+    """
 
     if help_config:
         return _show_config_help(help_config)

zappend/context.py

@@ -67,7 +67,10 @@ def zarr_version(self) -> int:
 
     @property
     def append_dim_name(self) -> str:
-        """The configured append dimension."""
+        """The name of the append dimension along which slice datasets will be
+        concatenated.
+        If not configured, it defaults to `"time"`.
+        """
         return self._config.get("append_dim") or DEFAULT_APPEND_DIM
 
     @property
@@ -83,7 +86,8 @@ def target_metadata(self, value: DatasetMetadata):
 
     @property
     def target_dir(self) -> FileObj:
-        """The configured target directory."""
+        """The configured directory that represents the target datacube
+        in Zarr format."""
         return self._target_dir
 
     @property