Merge branch 'main' into forman-55-lock_file_issue

# Conflicts:
#	CHANGES.md
#	docs/config.md

Author: forman

CHANGES.md

@@ -6,6 +6,11 @@
   reporting that the lock file to be written does not exist. Changed this to
   report that the target parent directory does not exist. [#55]
 
+### Enhancements
+
+* Added missing documentation of the `append_step` setting in the 
+  [configuration reference](https://bcdev.github.io/zappend/config/).
+
 ## Version 0.4.0 (from 2024-02-08)
 
 ### Enhancements

docs/config.md

@@ -4,13 +4,13 @@
 ## `version`
 
 Configuration schema version. Allows the schema to evolve while still preserving backwards compatibility.
-Its value must be `1`.
+Its value is `1`.
 Defaults to `1`.
 
 ## `zarr_version`
 
 The Zarr version to be used.
-Its value must be `2`.
+Its value is `2`.
 Defaults to `2`.
 
 ## `fixed_dims`
@@ -28,22 +28,23 @@ Defaults to `"time"`.
 ## `append_step`
 
 If set, enforces a step size in the append dimension between two slices or just enforces a direction.
-Must be one of the following.
+Must be one of the following:
 
   * Arbitrary step size or not applicable.
-    Its value must be `null`.
+    Its value is `null`.
 
   * Monotonically increasing.
-    Its value must be `"+"`.
+    Its value is `"+"`.
 
   * Monotonically decreasing.
-    Its value must be `"-"`.
+    Its value is `"-"`.
 
   * Type _string_.
-    A time delta value.
+    A positive or negative time delta value, such as `12h`, `2D`, `-1D`.
 
   * Type _number_.
-    A numerical delta value.
+    A positive or negative numerical delta value.
+
 Defaults to `null`.
 
 ## `included_variables`
@@ -80,27 +81,29 @@ Variable metadata.
 
       * `chunks`:
         Storage chunking.
-        Must be one of the following.
+        Must be one of the following:
 
           * Type _array_.
             Chunk sizes in the order of the dimensions.
             The items of the array are of type _integer_.
 
           * Disable chunking.
-            Its value must be `null`.
+            Its value is `null`.
+        
 
       * `fill_value`:
         Storage fill value.
-        Must be one of the following.
+        Must be one of the following:
 
           * Type _number_.
             A number of type and unit of the given storage `dtype`.
 
           * Not-a-number. Can be used only if storage `dtype` is `float32` or `float64`.
-            Its value must be `"NaN"`.
+            Its value is `"NaN"`.
 
           * No fill value.
-            Its value must be `null`.
+            Its value is `null`.
+        
 
       * `scale_factor`:
         Type _number_.
@@ -168,13 +171,13 @@ Options for the filesystem given by the protocol of the URIs of contributing dat
 ## `slice_polling`
 
 Defines how to poll for contributing datasets.
-Must be one of the following.
+Must be one of the following:
 
   * No polling, fail immediately if dataset is not available.
-    Its value must be `false`.
+    Its value is `false`.
 
   * Poll using default values.
-    Its value must be `true`.
+    Its value is `true`.
 
   * Type _object_.
     Polling parameters.
@@ -190,6 +193,7 @@ Must be one of the following.
         Polling timeout in seconds.
         Defaults to `60`.
 
+
 ## `persist_mem_slices`
 
 Type _boolean_.
@@ -215,7 +219,7 @@ Defaults to `false`.
 ## `profiling`
 
 Profiling configuration. Allows for runtime profiling of the processing.
-Must be one of the following.
+Must be one of the following:
 
   * Type _boolean_.
     If set, profiling is enabled and output is logged using level `"INFO"`. Otherwise, profiling is disabled.
@@ -248,7 +252,7 @@ Must be one of the following.
       * `restrictions`:
         Type _array_.
         Used to limit the list down to the significant entries in the profiling report. Refer to [Stats.print_stats(*restrictions)](https://docs.python.org/3/library/profile.html#pstats.Stats.print_stats).
-        The items of the array must be one of the following.
+        The items of the array must be one of the following:
 
           * Type _integer_.
             Select a count of lines.
@@ -258,6 +262,8 @@ Must be one of the following.
 
           * Type _string_.
             Pattern-match the standard name that is printed.
+        
+
 
 ## `logging`
 
@@ -267,7 +273,7 @@ The key `version` is required.
 
   * `version`:
     Logging schema version.
-    Its value must be `1`.
+    Its value is `1`.
 
   * `formatters`:
     Type _object_.

zappend/config/markdown.py

@@ -44,9 +44,9 @@ def _schema_to_md(
     one_of = schema.get("anyOf") or schema.get("oneOf")
     if one_of:
         if sequence_name:
-            lines.append(f"The {sequence_name} must be one of the following.")
+            lines.append(f"The {sequence_name} must be one of the following:")
         else:
-            lines.append("Must be one of the following.")
+            lines.append("Must be one of the following:")
         for sub_schema in one_of:
             sub_lines = []
             _schema_to_md(sub_schema, path, sub_lines)
@@ -55,11 +55,12 @@ def _schema_to_md(
                 lines.append("  * " + sub_lines[0])
                 for sub_line in sub_lines[1:]:
                     lines.append("    " + sub_line)
+        lines.append("")
 
     const = schema.get("const", undefined)
     if const is not undefined:
         value = json.dumps(const)
-        lines.append(f"Its value must be `{value}`.")
+        lines.append(f"Its value is `{value}`.")
 
     default = schema.get("default", undefined)
     if default is not undefined:

zappend/config/schema.py

@@ -487,12 +487,15 @@
                 {"description": "Monotonically increasing.", "const": "+"},
                 {"description": "Monotonically decreasing.", "const": "-"},
                 {
-                    "description": "A time delta value.",
+                    "description": (
+                        "A positive or negative time delta value,"
+                        " such as `12h`, `2D`, `-1D`."
+                    ),
                     "type": "string",
                     "not": {"const": ""},
                 },
                 {
-                    "description": "A numerical delta value.",
+                    "description": "A positive or negative numerical delta value.",
                     "type": "number",
                     "not": {"const": 0},
                 },