respond to david's review

Author: jhamman

docs/index.rst

@@ -51,8 +51,8 @@ Zarr is a file storage format for chunked, compressed, N-dimensional arrays base
     .. grid-item-card::
         :img-top: _static/index_user_guide.svg
 
-        Guide
-        ^^^^^
+       Guide
+       ^^^^^
 
        A detailed guide for how to use Zarr-Python.
 

docs/release.rst

@@ -1906,7 +1906,7 @@ Enhancements
 
 * **Advanced indexing**. The ``Array`` class has several new methods and
   properties that enable a selection of items in an array to be retrieved or
-  updated. See the :ref:`tutorial_indexing` tutorial section for more
+  updated. See the :ref:`user-guide-indexing` tutorial section for more
   information. There is also a `notebook
   <https://github.com/zarr-developers/zarr-python/blob/main/notebooks/advanced_indexing.ipynb>`_
   with extended examples and performance benchmarks. :issue:`78`, :issue:`89`,
@@ -1919,15 +1919,15 @@ Enhancements
   compressor codecs for Zstd and LZ4. This change is backwards-compatible with
   existing code, as all codec classes defined by Numcodecs are imported into the
   :mod:`zarr.codecs` namespace. However, it is recommended to import codecs from
-  the new package, see the tutorial sections on :ref:`tutorial_compress` and
-  :ref:`tutorial_filters` for examples. With contributions by
+  the new package, see the tutorial sections on :ref:`user-guide-compress` and
+  :ref:`user-guide-filters` for examples. With contributions by
   :user:`John Kirkham <jakirkham>`; :issue:`74`, :issue:`102`, :issue:`120`,
   :issue:`123`, :issue:`139`.
 
 * **New storage class for DBM-style databases**. The
   :class:`zarr.storage.DBMStore` class enables any DBM-style database such as gdbm,
   ndbm or Berkeley DB, to be used as the backing store for an array or group. See the
-  tutorial section on :ref:`tutorial_storage` for some examples. :issue:`133`,
+  tutorial section on :ref:`user-guide-storage` for some examples. :issue:`133`,
   :issue:`186`.
 
 * **New storage class for LMDB databases**. The :class:`zarr.storage.LMDBStore` class
@@ -1943,7 +1943,7 @@ Enhancements
   :func:`zarr.hierarchy.Group.tree` method which enables a tree representation of
   a group hierarchy to be printed. Also provides an interactive tree
   representation when used within a Jupyter notebook. See the
-  :ref:`tutorial_diagnostics` tutorial section for examples. By
+  :ref:`user-guide-diagnostics` tutorial section for examples. By
   :user:`John Kirkham <jakirkham>`; :issue:`82`, :issue:`140`, :issue:`184`.
 
 * **Visitor API**. The ``Group`` class now implements the h5py visitor API, see
@@ -1963,7 +1963,7 @@ Enhancements
   store. The functions :func:`zarr.convenience.save` and
   :func:`zarr.convenience.load` are also available and provide a convenient way to
   save an entire NumPy array to disk and load back into memory later. See the
-  tutorial section :ref:`tutorial_persist` for examples. :issue:`104`,
+  tutorial section :ref:`user-guide-persist` for examples. :issue:`104`,
   :issue:`105`, :issue:`141`, :issue:`181`.
 
 * **IPython completions**. The ``Group`` class now implements ``__dir__()`` and
@@ -1973,15 +1973,15 @@ Enhancements
 * **New info property; changes to __repr__**. The ``Group`` and
   ``Array`` classes have a new ``info`` property which can be used to print
   diagnostic information, including compression ratio where available. See the
-  tutorial section on :ref:`tutorial_diagnostics` for examples. The string
+  tutorial section on :ref:`user-guide-diagnostics` for examples. The string
   representation (``__repr__``) of these classes has been simplified to ensure
   it is cheap and quick to compute in all circumstances. :issue:`83`,
   :issue:`115`, :issue:`132`, :issue:`148`.
 
 * **Chunk options**. When creating an array, ``chunks=False`` can be specified,
   which will result in an array with a single chunk only. Alternatively,
   ``chunks=True`` will trigger an automatic chunk shape guess. See
-  :ref:`tutorial_chunks` for more on the ``chunks`` parameter. :issue:`106`,
+  :ref:`user-guide-chunks` for more on the ``chunks`` parameter. :issue:`106`,
   :issue:`107`, :issue:`183`.
 
 * **Zero-dimensional arrays** and are now supported; by
@@ -2006,7 +2006,7 @@ Enhancements
   creating an array with ``dtype=object`` was possible but could under certain
   circumstances lead to unexpected errors and/or segmentation faults. To make it easier
   to properly configure an object array, a new ``object_codec`` parameter has been
-  added to array creation functions. See the tutorial section on :ref:`tutorial_objects`
+  added to array creation functions. See the tutorial section on :ref:`user-guide-objects`
   for more information and examples. Also, runtime checks have been added in both Zarr
   and Numcodecs so that segmentation faults are no longer possible, even with a badly
   configured array. This API change is backwards compatible and previous code that created
@@ -2062,16 +2062,16 @@ Documentation
   with any of the material as previously implemented, and so the changes have been made
   in-place in the document without incrementing the document version number. See the
   section on changes in the specification document for more information.
-* A new :ref:`tutorial_indexing` section has been added to the tutorial.
-* A new :ref:`tutorial_strings` section has been added to the tutorial
+* A new :ref:`user-guide-indexing` section has been added to the tutorial.
+* A new :ref:`user-guide-strings` section has been added to the tutorial
   (:issue:`135`, :issue:`175`).
-* The :ref:`tutorial_chunks` tutorial section has been reorganised and updated.
-* The :ref:`tutorial_persist` and :ref:`tutorial_storage` tutorial sections have
+* The :ref:`user-guide-chunks` tutorial section has been reorganised and updated.
+* The :ref:`user-guide-persist` and :ref:`user-guide-storage` tutorial sections have
   been updated with new examples (:issue:`100`, :issue:`101`, :issue:`103`).
-* A new tutorial section on :ref:`tutorial_pickle` has been added (:issue:`91`).
-* A new tutorial section on :ref:`tutorial_datetime` has been added.
-* A new tutorial section on :ref:`tutorial_diagnostics` has been added.
-* The tutorial sections on :ref:`tutorial_sync` and :ref:`tutorial_tips_blosc` have been
+* A new tutorial section on :ref:`user-guide-pickle` has been added (:issue:`91`).
+* A new tutorial section on :ref:`user-guide-datetime` has been added.
+* A new tutorial section on :ref:`user-guide-diagnostics` has been added.
+* The tutorial sections on :ref:`user-guide-sync` and :ref:`user-guide-tips-blosc` have been
   updated to provide information about how to avoid program hangs when using the Blosc
   compressor with multiple processes (:issue:`199`, :issue:`201`).
 
@@ -2177,14 +2177,14 @@ Hierarchies
 ~~~~~~~~~~~
 
 Support has been added for organizing arrays into hierarchies via groups. See
-the tutorial section on :ref:`tutorial_groups` and the :mod:`zarr.hierarchy`
+the tutorial section on :ref:`user-guide-groups` and the :mod:`zarr.hierarchy`
 API docs for more information.
 
 Filters
 ~~~~~~~
 
 Support has been added for configuring filters to preprocess chunk data prior
-to compression. See the tutorial section on :ref:`tutorial_filters` and the
+to compression. See the tutorial section on :ref:`user-guide-filters` and the
 :mod:`zarr.codecs` API docs for more information.
 
 Other changes
@@ -2210,7 +2210,7 @@ Thanks to :user:`Matthew Rocklin <mrocklin>`, :user:`Stephan Hoyer <shoyer>` and
 
 * The bundled Blosc library has been upgraded to version 1.10.0. The 'zstd'
   internal compression library is now available within Blosc. See the tutorial
-  section on :ref:`tutorial_compress` for an example.
+  section on :ref:`user-guide-compress` for an example.
 * When using the Blosc compressor, the default internal compression library
   is now 'lz4'.
 * The default number of internal threads for the Blosc compressor has been
@@ -2236,8 +2236,8 @@ The main motivation for re-organizing the code was to create an
 abstraction layer between the core array logic and data storage (:issue:`21`).
 In this release, any
 object that implements the ``MutableMapping`` interface can be used as
-an array store. See the tutorial sections on :ref:`tutorial_persist`
-and :ref:`tutorial_storage`, the ``spec_v1``, and the
+an array store. See the tutorial sections on :ref:`user-guide-persist`
+and :ref:`user-guide-storage`, the ``spec_v1``, and the
 :mod:`zarr.storage` module documentation for more information.
 
 Please note also that the file organization and file name conventions
@@ -2256,8 +2256,8 @@ chunks. This release still bundles the c-blosc library and uses Blosc
 as the default compressor, however other compressors including zlib,
 BZ2 and LZMA are also now supported via the Python standard
 library. New compressors can also be dynamically registered for use
-with Zarr. See the tutorial sections on :ref:`tutorial_compress` and
-:ref:`tutorial_tips_blosc`, the ``spec_v1``, and the
+with Zarr. See the tutorial sections on :ref:`user-guide-compress` and
+:ref:`user-guide-tips-blosc`, the ``spec_v1``, and the
 :mod:`zarr.compressors` module documentation for more information.
 
 Synchronization
@@ -2266,7 +2266,7 @@ Synchronization
 The synchronization code has also been refactored to create a layer of
 abstraction, enabling Zarr arrays to be used in parallel computations
 with a number of alternative synchronization methods. For more
-information see the tutorial section on :ref:`tutorial_sync` and the
+information see the tutorial section on :ref:`user-guide-sync` and the
 :mod:`zarr.sync` module documentation.
 
 Changes to the Blosc extension
@@ -2288,7 +2288,7 @@ is running within a single-threaded or multi-threaded program and
 adapts its internal behaviour accordingly (:issue:`27`). There is no need for
 the user to make any API calls to switch Blosc between contextual and
 non-contextual (global lock) mode. See also the tutorial section on
-:ref:`tutorial_tips_blosc`.
+:ref:`user-guide-tips-blosc`.
 
 Other changes
 ~~~~~~~~~~~~~
@@ -2302,7 +2302,7 @@ option present in the previous release, and this has been removed.
 The memory layout within chunks can now be set as either "C"
 (row-major) or "F" (column-major), which can help to provide better
 compression for some data (:issue:`7`). See the tutorial
-section on :ref:`tutorial_chunks_order` for more information.
+section on :ref:`user-guide-chunks-order` for more information.
 
 A bug has been fixed within the ``__getitem__`` and ``__setitem__``
 machinery for slicing arrays, to properly handle getting and setting

docs/user-guide/arrays.rst

@@ -1,11 +1,12 @@
+.. _user-guide-arrays:
 
-Working with Arrays
+Working with arrays
 ===================
 
-.. ipython::
+.. ipython:: python
    :suppress:
 
-   In [144]: rm -r data/
+   rm -r data/
 
 Creating an array
 -----------------
@@ -30,17 +31,17 @@ The code above creates a 2-dimensional array of 32-bit integers with 10000 rows
 and 10000 columns, divided into chunks where each chunk has 1000 rows and 1000
 columns (and so there will be 100 chunks in total). The data is written to a
 :class:`zarr.storage.MemoryStore` (e.g. an in-memory dict). See
-:ref:`tutorial_persist` for details on storing arrays in other stores.
+:ref:`user-guide-persist` for details on storing arrays in other stores.
 
-For a complete list of array creation routines see the :mod:`zarr.api.synchronous`
+For a complete list of array creation routines see the :mod:`zarr`
 module documentation.
 
-.. _tutorial_array:
+.. _user-guide-array:
 
 Reading and writing data
 ------------------------
 
-Zarr arrays support a similar interface to `NumPy <https://numpy.org/doc/stable/>`
+Zarr arrays support a similar interface to `NumPy <https://numpy.org/doc/stable/>`_
 arrays for reading and writing data. For example, the entire array can be filled
 with a scalar value:
 
@@ -68,14 +69,18 @@ requested region into memory as a NumPy array, e.g.:
    z[:, 0]
    z[:]
 
-.. _tutorial_persist:
+Read more about NumPy-style indexing can be found in the
+`NumPy documentation <https://numpy.org/doc/stable/user/basics.indexing.html>`_.
+
+.. _user-guide-persist:
 
 Persistent arrays
 -----------------
 
 In the examples above, compressed data for each chunk of the array was stored in
 main memory. Zarr arrays can also be stored on a file system, enabling
-persistence of data between sessions. For example:
+persistence of data between sessions. To do this, we can change the store
+argument to point to a filesystem path:
 
 .. ipython:: python
 
@@ -88,7 +93,7 @@ persistence of data between sessions. For example:
    )
 
 The array above will store its configuration metadata and all compressed chunk
-data in a directory called ``'data/example.zarr'`` relative to the current working
+data in a directory called ``'data/example-2.zarr'`` relative to the current working
 directory. The :func:`zarr.open` function provides a convenient way
 to create a new persistent array or continue working with an existing
 array. Note that although the function is called "open", there is no need to
@@ -123,9 +128,9 @@ useful. E.g.:
    zarr.load('data/example-3.zarr')
 
 Please note that there are a number of other options for persistent array
-storage, see the :ref:`tutorial_storage` guide for more details.
+storage, see the :ref:`Storage Guide <user-guide-storage>` guide for more details.
 
-.. _tutorial_resize:
+.. _user-guide-resize:
 
 Resizing and appending
 ----------------------
@@ -161,7 +166,7 @@ used to append data to any axis. E.g.:
    z.append(np.vstack([a, a]), axis=1)
    z.shape
 
-.. _tutorial_compress:
+.. _user-guide-compress:
 
 Compressors
 -----------
@@ -187,7 +192,7 @@ algorithm (compression level 3) internally within Blosc, and with the
 bit-shuffle filter applied.
 
 When using a compressor, it can be useful to get some diagnostics on the
-compression ratio. Zarr arrays provide the :func:`zarr.Array.info` property
+compression ratio. Zarr arrays provide the :property:`zarr.Array.info` property
 which can be used to print useful diagnostics, e.g.:
 
 .. ipython:: python
@@ -201,6 +206,11 @@ prints additional diagnostics, e.g.:
 
    z.info_complete()
 
+.. note::
+   :func:`zarr.Array.info_complete` will inspect the underlying store and may
+   be slow for large arrays. Use :property:`zarr.Array.info` if detailed storage
+   statistics are not needed.
+
 If you don't specify a compressor, by default Zarr uses the Blosc
 compressor. Blosc is generally very fast and can be configured in a variety of
 ways to improve the compression ratio for different types of data. Blosc is in
@@ -252,7 +262,7 @@ built-in delta filter:
    None  # TODO: z.compressor
 
 The default compressor can be changed by setting the value of the using Zarr's
-:ref:`config`, e.g.:
+:ref:`user-guide-config`, e.g.:
 
 .. ipython:: python
 
@@ -269,7 +279,7 @@ To disable compression, set ``compressor=None`` when creating an array, e.g.:
    # TODO: remove zarr_format
    z = zarr.zeros(100000000, chunks=1000000, compressor=None, zarr_format=2)
    z
-.. _tutorial_filters:
+.. _user-guide-filters:
 
 Filters
 -------
@@ -301,7 +311,7 @@ Here is an example using a delta filter with the Blosc compressor:
 For more information about available filter codecs, see the `Numcodecs
 <https://numcodecs.readthedocs.io/>`_ documentation.
 
-.. _tutorial_indexing:
+.. _user-guide-indexing:
 
 Advanced indexing
 -----------------
@@ -522,7 +532,44 @@ Any combination of integer and slice can be used for block indexing:
    bar[:] = np.arange(100)
    root.tree()
 
+.. _user-guide-sharding:
+
 Sharding
 --------
 
 Coming soon.
+
+
+Missing features in 3.0
+-----------------------
+
+
+The following features have not been ported to 3.0 yet.
+
+.. _user-guide-objects:
+
+Object arrays
+~~~~~~~~~~~~~
+
+See the Zarr-Python 2 documentation on `Object arrays <https://zarr.readthedocs.io/en/support-v2/tutorial.html#object-arrays>`_ for more details.
+
+.. _user-guide-strings:
+
+Fixed-length string arrays
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+See the Zarr-Python 2 documentation on `Fixed-length string arrays <https://zarr.readthedocs.io/en/support-v2/tutorial.html#string-arrays>`_ for more details.
+
+.. _user-guide-datetime:
+
+Datetime and Timedelta arrays
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+See the Zarr-Python 2 documentation on `Datetime and Timedelta <https://zarr.readthedocs.io/en/support-v2/tutorial.html#datetimes-and-timedeltas>`_ for more details.
+
+.. _user-guide-copy:
+
+Copying and migrating data
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+See the Zarr-Python 2 documentation on `Copying and migrating data <https://zarr.readthedocs.io/en/support-v2/tutorial.html#copying-migrating-data>`_ for more details.

docs/user-guide/attributes.rst

@@ -1,4 +1,4 @@
-.. _tutorial_attrs:
+.. _user-guide-attrs:
 
 Working with attributes
 =======================

docs/user-guide/config.rst

@@ -1,4 +1,4 @@
-.. _config:
+.. _user-guide-config:
 
 Runtime configuration
 =====================
@@ -8,11 +8,17 @@ and is based on the `donfig <https://github.com/pytroll/donfig>`_ Python library
 
 Configuration values can be set using code like the following:
 
-.. code-block:: python
+.. ipython:: python
 
     import zarr
     zarr.config.set({"array.order": "F"})
 
+.. ipython:: python
+   :suppress:
+
+    # revert this change so it doesn't impact the rest of the docs
+    zarr.config.set({"array.order": "C"})
+
 Alternatively, configuration values can be set using environment variables, e.g.
 ``ZARR_ARRAY__ORDER=F``.