docs: add docs on using asyncio with zarr

Author: jhamman

docs/user-guide/async.rst

@@ -0,0 +1,36 @@
+
+Async Zarr
+==========
+
+Zarr-Python 3 added a new asynchronous API for reading and writing data using `asyncio`.
+
+The usage of the async API mirrors the synchronous API.
+
+.. ipython:: python
+
+   import asyncio
+   import numpy as np
+   import zarr.api.asynchronous as async_zarr
+
+   # create a new group using the asynchronous API
+   root = await async_zarr.group(attributes={'foo': 'bar'})
+   root
+   # create an array using the AsyncGroup
+   z = await root.create_array(name='foo', shape=(100, ), chunks=(5, ), dtype='i4')
+   z
+   # set and get items
+   await z.setitem((slice(None), ), np.arange(0, 100, dtype=z.dtype))
+   # set a single item
+   await z.setitem((7,), -99)
+   # set a range to a constant value using a slice
+   await z.setitem(slice(0, 3), -1)
+   # get a slice of the array
+   await z.getitem((slice(0, 5), ))
+   # gather multiple items concurrently
+   await asyncio.gather(z.getitem(slice(0, 5)), z.getitem(slice(6, 10)))
+
+See the API docs for more details:
+
+* :mod:`zarr.api.asynchronous`
+* :class:`zarr.AsyncArray`
+* :class:`zarr.AsyncGroup`

docs/user-guide/index.rst

@@ -23,11 +23,11 @@ Advanced Topics
     :maxdepth: 1
 
     performance
+    async
     consolidated_metadata
     whatsnew_v3
     v3_todos
 
 
 .. Coming soon
-    async
     extending