improve docstring readability

Author: brokkoli71

src/zarr/api/asynchronous.py

@@ -835,20 +835,25 @@ async def create(
         An iterable of Codec or dict serializations of Codecs. The elements of
         this collection specify the transformation from array values to stored bytes.
         V3 only. V2 arrays should use ``filters`` and ``compressor`` instead.
+
         If no codecs are provided, default codecs will be used:
+
         - For numeric arrays, the default is ``BytesCodec`` and ``ZstdCodec``.
         - For Unicode strings, the default is ``VLenUTF8Codec``.
         - For bytes or objects, the default is ``VLenBytesCodec``.
-        These defaults can be changed using the ``array.v3_default_codecs`` variable in :mod:`zarr.core.config`.
+
+        These defaults can be changed by modifying the value of ``array.v3_default_codecs`` in :mod:`zarr.core.config`.
     compressor : Codec, optional
         Primary compressor to compress chunk data.
         V2 only. V3 arrays should use ``codecs`` instead.
+
         If neither ``compressor`` nor ``filters`` are provided, a default compressor will be used:
+
         - For numeric arrays, the default is ``ZstdCodec``.
         - For Unicode strings, the default is ``VLenUTF8Codec``.
         - For bytes or objects, the default is ``VLenBytesCodec``.
-        These defaults can be changed using the ``array.v2_default_compressor`` variable in :mod:`zarr.core.config`.
-    fill_value : object
+
+        These defaults can be changed by modifying the value of ``array.v2_default_compressor`` in :mod:`zarr.core.config`.    fill_value : object
         Default value to use for uninitialized portions of the array.
     order : {'C', 'F'}, optional
         Memory layout to be used within each chunk.

src/zarr/core/array.py

@@ -420,11 +420,14 @@ async def create(
             An iterable of Codec or dict serializations of Codecs. The elements of
             this collection specify the transformation from array values to stored bytes.
             V3 only. V2 arrays should use ``filters`` and ``compressor`` instead.
+
             If no codecs are provided, default codecs will be used:
+
             - For numeric arrays, the default is ``BytesCodec`` and ``ZstdCodec``.
             - For Unicode strings, the default is ``VLenUTF8Codec``.
             - For bytes or objects, the default is ``VLenBytesCodec``.
-            These defaults can be changed using the ``array.v3_default_codecs`` variable in :mod:`zarr.core.config`.
+
+            These defaults can be changed by modifying the value of ``array.v3_default_codecs`` in :mod:`zarr.core.config`.
         dimension_names : Iterable[str], optional
             The names of the dimensions (default is None).
             V3 only. V2 arrays should not use this parameter.
@@ -445,11 +448,14 @@ async def create(
         compressor : dict[str, JSON], optional
             The compressor used to compress the data (default is None).
             V2 only. V3 arrays should use ``codecs`` instead.
+
             If neither ``compressor`` nor ``filters`` are provided, a default compressor will be used:
+
             - For numeric arrays, the default is ``ZstdCodec``.
             - For Unicode strings, the default is ``VLenUTF8Codec``.
             - For bytes or objects, the default is ``VLenBytesCodec``.
-            These defaults can be changed using the ``array.v2_default_compressor`` variable in :mod:`zarr.core.config`.
+
+            These defaults can be changed by modifying the value of ``array.v2_default_compressor`` in :mod:`zarr.core.config`.
         overwrite : bool, optional
             Whether to raise an error if the store already exists (default is False).
         data : npt.ArrayLike, optional
@@ -1512,11 +1518,14 @@ def create(
             An iterable of Codec or dict serializations of Codecs. The elements of
             this collection specify the transformation from array values to stored bytes.
             V3 only. V2 arrays should use ``filters`` and ``compressor`` instead.
+
             If no codecs are provided, default codecs will be used:
+
             - For numeric arrays, the default is ``BytesCodec`` and ``ZstdCodec``.
             - For Unicode strings, the default is ``VLenUTF8Codec``.
             - For bytes or objects, the default is ``VLenBytesCodec``.
-            These defaults can be changed using the ``array.v3_default_codecs`` variable in :mod:`zarr.core.config`.
+
+            These defaults can be changed by modifying the value of ``array.v3_default_codecs`` in :mod:`zarr.core.config`.
         dimension_names : Iterable[str], optional
             The names of the dimensions (default is None).
             V3 only. V2 arrays should not use this parameter.
@@ -1537,11 +1546,14 @@ def create(
         compressor : dict[str, JSON], optional
             Primary compressor to compress chunk data.
             V2 only. V3 arrays should use ``codecs`` instead.
+
             If neither ``compressor`` nor ``filters`` are provided, a default compressor will be used:
+
             - For numeric arrays, the default is ``ZstdCodec``.
             - For Unicode strings, the default is ``VLenUTF8Codec``.
             - For bytes or objects, the default is ``VLenBytesCodec``.
-            These defaults can be changed using the ``array.v2_default_compressor`` variable in :mod:`zarr.core.config`.
+
+            These defaults can be changed by modifying the value of ``array.v2_default_compressor`` in :mod:`zarr.core.config`.
         overwrite : bool, optional
             Whether to raise an error if the store already exists (default is False).
 

src/zarr/core/config.py

@@ -1,13 +1,28 @@
 """
-The config module is responsible for managing the configuration of zarr and  is based on the Donfig python library.
+The config module is responsible for managing the configuration of zarr and is based on the Donfig python library.
 For selecting custom implementations of codecs, pipelines, buffers and ndbuffers, first register the implementations
 in the registry and then select them in the config.
-e.g. an implementation of the bytes codec in a class "your.module.NewBytesCodec", requires the value of codecs.bytes
-to be "your.module.NewBytesCodec".
-Donfig can be configured programmatically, by environment variables, or from YAML files in standard locations
-e.g. export ZARR_CODECS__BYTES="your.module.NewBytesCodec"
-(for more information see github.com/pytroll/donfig)
-Default values below point to the standard implementations of zarr-python
+
+Example:
+    An implementation of the bytes codec in a class `your.module.NewBytesCodec` requires the value of `codecs.bytes`
+    to be `your.module.NewBytesCodec`.
+
+    ```python
+    from your.module import NewBytesCodec
+    from zarr.core.config import register_codec, config
+
+    register_codec("bytes", NewBytesCodec)
+    config.set({"codecs.bytes": "your.module.NewBytesCodec"})
+    ```
+
+Donfig can be configured programmatically, by environment variables, or from YAML files in standard locations.
+For example, to set the bytes codec via an environment variable:
+
+    export ZARR_CODECS__BYTES="your.module.NewBytesCodec"
+
+For more information, see the Donfig documentation at https://github.com/pytroll/donfig.
+
+Default values below point to the standard implementations of zarr-python.
 """
 
 from __future__ import annotations

src/zarr/core/group.py

@@ -1045,11 +1045,14 @@ async def create_array(
             An iterable of Codec or dict serializations of Codecs. The elements of
             this collection specify the transformation from array values to stored bytes.
             V3 only. V2 arrays should use ``filters`` and ``compressor`` instead.
+
             If no codecs are provided, default codecs will be used:
+
             - For numeric arrays, the default is ``BytesCodec`` and ``ZstdCodec``.
             - For Unicode strings, the default is ``VLenUTF8Codec``.
             - For bytes or objects, the default is ``VLenBytesCodec``.
-            These defaults can be changed using the ``array.v3_default_codecs`` variable in :mod:`zarr.core.config`.
+
+            These defaults can be changed by modifying the value of ``array.v3_default_codecs`` in :mod:`zarr.core.config`.
         dimension_names : Iterable[str] | None = None
             The names of the dimensions of the array. V3 only.
         chunks : ChunkCoords | None = None
@@ -1069,11 +1072,14 @@ async def create_array(
         compressor : dict[str, JSON] | None = None
             The compressor used to compress the data (default is None).
             V2 only. V3 arrays should use ``codecs`` instead.
+
             If neither ``compressor`` nor ``filters`` are provided, a default compressor will be used:
+
             - For numeric arrays, the default is ``ZstdCodec``.
             - For Unicode strings, the default is ``VLenUTF8Codec``.
             - For bytes or objects, the default is ``VLenBytesCodec``.
-            These defaults can be changed using the ``array.v2_default_compressor`` variable in :mod:`zarr.core.config`.
+
+            These defaults can be changed by modifying the value of ``array.v2_default_compressor`` in :mod:`zarr.core.config`.
         overwrite : bool = False
             If True, a pre-existing array or group at the path of this array will
             be overwritten. If False, the presence of a pre-existing array or group is
@@ -2266,11 +2272,14 @@ def create_array(
             An iterable of Codec or dict serializations of Codecs. The elements of
             this collection specify the transformation from array values to stored bytes.
             V3 only. V2 arrays should use ``filters`` and ``compressor`` instead.
+
             If no codecs are provided, default codecs will be used:
+
             - For numeric arrays, the default is ``BytesCodec`` and ``ZstdCodec``.
             - For Unicode strings, the default is ``VLenUTF8Codec``.
             - For bytes or objects, the default is ``VLenBytesCodec``.
-            These defaults can be changed using the ``array.v3_default_codecs`` variable in :mod:`zarr.core.config`.
+
+            These defaults can be changed by modifying the value of ``array.v3_default_codecs`` in :mod:`zarr.core.config`.
         dimension_names : Iterable[str] | None = None
             The names of the dimensions of the array. V3 only.
         chunks : ChunkCoords | None = None
@@ -2290,11 +2299,14 @@ def create_array(
         compressor : dict[str, JSON] | None = None
             The compressor used to compress the data (default is None).
             V2 only. V3 arrays should use ``codecs`` instead.
+
             If neither ``compressor`` nor ``filters`` are provided, a default compressor will be used:
+
             - For numeric arrays, the default is ``ZstdCodec``.
             - For Unicode strings, the default is ``VLenUTF8Codec``.
             - For bytes or objects, the default is ``VLenBytesCodec``.
-            These defaults can be changed using the ``array.v2_default_compressor`` variable in :mod:`zarr.core.config`.
+
+            These defaults can be changed by modifying the value of ``array.v2_default_compressor`` in :mod:`zarr.core.config`.
         overwrite : bool = False
             If True, a pre-existing array or group at the path of this array will
             be overwritten. If False, the presence of a pre-existing array or group is
@@ -2630,11 +2642,14 @@ def array(
             An iterable of Codec or dict serializations of Codecs. The elements of
             this collection specify the transformation from array values to stored bytes.
             V3 only. V2 arrays should use ``filters`` and ``compressor`` instead.
+
             If no codecs are provided, default codecs will be used:
+
             - For numeric arrays, the default is ``BytesCodec`` and ``ZstdCodec``.
             - For Unicode strings, the default is ``VLenUTF8Codec``.
             - For bytes or objects, the default is ``VLenBytesCodec``.
-            These defaults can be changed using the ``array.v3_default_codecs`` variable in :mod:`zarr.core.config`.
+
+            These defaults can be changed by modifying the value of ``array.v3_default_codecs`` in :mod:`zarr.core.config`.
         dimension_names : Iterable[str] | None = None
             The names of the dimensions of the array. V3 only.
         chunks : ChunkCoords | None = None
@@ -2654,11 +2669,14 @@ def array(
         compressor : dict[str, JSON] | None = None
             The compressor used to compress the data (default is None).
             V2 only. V3 arrays should use ``codecs`` instead.
+
             If neither ``compressor`` nor ``filters`` are provided, a default compressor will be used:
+
             - For numeric arrays, the default is ``ZstdCodec``.
             - For Unicode strings, the default is ``VLenUTF8Codec``.
             - For bytes or objects, the default is ``VLenBytesCodec``.
-            These defaults can be changed using the ``array.v2_default_compressor`` variable in :mod:`zarr.core.config`.
+
+            These defaults can be changed by modifying the value of ``array.v2_default_compressor`` in :mod:`zarr.core.config`.
         overwrite : bool = False
             If True, a pre-existing array or group at the path of this array will
             be overwritten. If False, the presence of a pre-existing array or group is