Enhanced docs

Author: forman

docs/api.md

@@ -46,8 +46,10 @@ All described objects can be imported from the `zappend.api` module.
     options:
         show_root_heading: true
 
-## Function `write_levels()` for `xcube` 
+## Contributions
 
-::: zappend.levels.write_levels
-    options:
-        show_root_heading: true
+::: zappend.contrib
+
+### Function `write_levels()`
+
+::: zappend.contrib.write_levels

zappend/contrib/__init__.py

@@ -2,4 +2,14 @@
 # Permissions are hereby granted under the terms of the MIT License:
 # https://opensource.org/licenses/MIT.
 
+"""
+This module contributes to zappend's core functionality.
+
+The function signatures in this module are less stable, and their implementations
+are considered experimental. They may also rely on external packages. For more
+information, please refer to the individual function documentation.
+Due to these reasons, this module is excluded from the project's automatic
+coverage analysis.
+"""
+
 from .levels import write_levels

zappend/contrib/levels.py

@@ -31,7 +31,7 @@ def write_levels(
     xy_dim_names: tuple[str, str] | None = None,
     **zappend_config,
 ):
-    """Writes a dataset given by `source_ds` or `source_path` to `target_path`
+    """Write a dataset given by `source_ds` or `source_path` to `target_path`
     using the
     [multi-level dataset format](https://xcube.readthedocs.io/en/latest/mldatasets.html)
     as specified by
@@ -59,7 +59,17 @@ def write_levels(
     If configuration parameter `variables` is also given as part of
     `zappend_config`, it will be merged with the chunk definitions.
 
-    Important: This function requires the `xcube` package to be installed.
+    **Important notes:**
+
+    - This function requires the `xcube` package.
+    - `write_levels()` is not as robust as zappend itself. For example,
+      there may be inconsistent dataset levels if the processing
+      is interrupted while a level is appended.
+    - There is a remaining issue that with (coordinate) variables that
+      have a dimension that is not a dimension of any variable that has
+      one of the spatial dimensions, e.g., `time_bnds` with dimensions
+      `time` and `bnds`. Please exclude such variables using the parameter
+      `excluded_variables`.
 
     Args:
         source_ds: The source dataset.