review docs

Author: alimanfoo

docs/spec/v2.rst

@@ -4,7 +4,7 @@ Zarr storage specification version 2
 ====================================
 
 This document provides a technical specification of the protocol and format 
-used for storing a Zarr array. The key words "MUST", "MUST NOT", "REQUIRED", 
+used for storing Zarr arrays. The key words "MUST", "MUST NOT", "REQUIRED", 
 "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and 
 "OPTIONAL" in this document are to be interpreted as described in `RFC 2119 
 <https://www.ietf.org/rfc/rfc2119.txt>`_.
@@ -56,12 +56,10 @@ chunks
 dtype
     A string or list defining a valid data type for the array. See also
     the subsection below on data type encoding.
-compression
-    A string identifying the primary compression library used to compress
-    each chunk of the array.
-compression_opts
-    An integer, string or dictionary providing options to the primary
-    compression library.
+compressor
+    A JSON object identifying the primary compression codec and providing 
+    configuration parameters, or ``null`` if no compressor is to be used. 
+    The object MUST contain an ``"id"`` key identifying the codec to be used.
 fill_value
     A scalar value providing the default value to use for uninitialized
     portions of the array, or ``null`` if no fill_value is to be used.
@@ -70,9 +68,9 @@ order
     array. "C" means row-major order, i.e., the last dimension varies fastest;
     "F" means column-major order, i.e., the first dimension varies fastest.
 filters
-    A list of JSON objects providing filter configurations, or ``null`` if no
-    filters are to be applied. Each filter configuration object MUST contain a
-    ``"name"`` key identifying the filter to be used.
+    A list of JSON objects providing codec configurations, or ``null`` if no
+    filters are to be applied. Each codec configuration object MUST contain a
+    ``"id"`` key identifying the codec to be used.
 
 Other keys MUST NOT be present within the metadata object.
 
@@ -88,16 +86,16 @@ using the Blosc compression library prior to storage::
             1000,
             1000
         ],
-        "compression": "blosc",
-        "compression_opts": {
-            "clevel": 5,
+        "compressor": {
+            "id": "blosc",
             "cname": "lz4",
+            "clevel": 5,
             "shuffle": 1
         },
         "dtype": "<f8",
         "fill_value": "NaN",
         "filters": [
-            {"name": "delta", "dtype": "<f8", "astype": "<f4"}
+            {"id": "delta", "dtype": "<f8", "astype": "<f4"}
         ],
         "order": "C",
         "shape": [

docs/tutorial.rst

@@ -236,8 +236,6 @@ the delta filter::
 
 To disable compression, set ``compressor=None`` when creating an array.
 
-To disable compression, set ``compression=None`` when creating an array.
-
 .. _tutorial_filters:
 
 Filters
@@ -270,7 +268,7 @@ Here is an example using the Zarr delta filter with the Blosc compressor:
 
 Zarr comes with implementations of delta, scale-offset, quantize, packbits and
 categorize filters. It is also relatively straightforward to implement custom
-filters. For more information see the :mod:`zarr.filters` API docs.
+filters. For more information see the :mod:`zarr.codecs` API docs.
 
 .. _tutorial_sync:
 
@@ -583,6 +581,14 @@ to find a compromise, e.g.::
     >>> z3.chunks
     (1000, 1000)
 
+If you are feeling lazy, you can let Zarr guess a chunk shape for your data,
+although please note that the algorithm for guessing a chunk shape is based on
+simple heuristics and may by far from optimal. E.g.::
+
+    >>> z4 = zarr.zeros((10000, 10000), dtype='i4')
+    >>> z4.chunks
+    (313, 313)
+
 .. _tutorial_tips_blosc:
 
 Configuring Blosc