Execute examples in quickstart

Author: maxrjones

docs/quick-start.md

@@ -5,32 +5,29 @@ the Zarr library in Python to efficiently manage and analyze multi-dimensional a
 
 To get started, you can create a simple Zarr array:
 
-```python
+```python exec="true" session="quickstart"
+import shutil
+shutil.rmtree('data', ignore_errors=True)
+import numpy as np
+
+np.random.seed(0)
+```
+
+```python exec="true" session="quickstart" source="material-block" result="ansi"
 import zarr
 import numpy as np
 
 # Create a 2D Zarr array
 z = zarr.create_array(
-   store="data/example-1.zarr",
-   shape=(100, 100),
-   chunks=(10, 10),
-   dtype="f4"
+    store="data/example-1.zarr",
+    shape=(100, 100),
+    chunks=(10, 10),
+    dtype="f4"
 )
 
 # Assign data to the array
 z[:, :] = np.random.random((100, 100))
-z.info
-
-# Type               : Array
-# Zarr format        : 3
-# Data type          : DataType.float32
-# Shape              : (100, 100)
-# Chunk shape        : (10, 10)
-# Order              : C
-# Read-only          : False
-# Store type         : LocalStore
-# Codecs             : [{'endian': <Endian.little: 'little'>}, {'level': 0, 'checksum': False}]
-# No. bytes          : 40000 (39.1K)
+print(z.info)
 ```
 
 Here, we created a 2D array of shape `(100, 100)`, chunked into blocks of
@@ -41,36 +38,38 @@ written to a `LocalStore` in the `data/example-1.zarr` directory.
 
 Zarr supports data compression and filters. For example, to use Blosc compression:
 
-```python
+
+```python exec="true" session="quickstart" source="material-block" result="ansi"
+
+# Create a 2D Zarr array with Blosc compression
 z = zarr.create_array(
-   "data/example-3.zarr",
-   mode="w", shape=(100, 100),
-   chunks=(10, 10), dtype="f4",
-   compressors=zarr.codecs.BloscCodec(cname="zstd", clevel=3, shuffle=zarr.codecs.BloscShuffle.shuffle)
+    store="data/example-2.zarr",
+    shape=(100, 100),
+    chunks=(10, 10),
+    dtype="f4",
+    compressors=zarr.codecs.BloscCodec(
+        cname="zstd",
+        clevel=3,
+        shuffle=zarr.codecs.BloscShuffle.shuffle
+    )
 )
+
+# Assign data to the array
 z[:, :] = np.random.random((100, 100))
-z.info
-# Type               : Array
-# Zarr format        : 3
-# Data type          : DataType.float32
-# Shape              : (100, 100)
-# Chunk shape        : (10, 10)
-# Order              : C
-# Read-only          : False
-# Store type         : LocalStore
-# Codecs             : [{'endian': <Endian.little: 'little'>}, {'level': 0, 'checksum': False}]
-# No. bytes          : 40000 (39.1K)
+print(z.info)
 ```
 
-This compresses the data using the Zstandard codec with shuffle enabled for better compression.
+This compresses the data using the Blosc codec with shuffle enabled for better compression.
+
 
 ### Hierarchical Groups
 
 Zarr allows you to create hierarchical groups, similar to directories:
 
-```python
+```python exec="true" session="quickstart" source="material-block" result="ansi"
+
 # Create nested groups and add arrays
-root = zarr.group("data/example-2.zarr")
+root = zarr.group("data/example-3.zarr")
 foo = root.create_group(name="foo")
 bar = root.create_array(
     name="bar", shape=(100, 10), chunks=(10, 10), dtype="f4"
@@ -82,11 +81,7 @@ bar[:, :] = np.random.random((100, 10))
 spam[:] = np.arange(10)
 
 # print the hierarchy
-root.tree()
-# /
-# ├── bar (100, 10) float32
-# └── foo
-#     └── spam (10,) int32
+print(root.tree())
 ```
 
 This creates a group with two datasets: `foo` and `bar`.
@@ -96,17 +91,17 @@ This creates a group with two datasets: `foo` and `bar`.
 Zarr provides tools for creating a collection of arrays and groups with a single function call.
 Suppose we want to copy existing groups and arrays into a new storage backend:
 
-```python
+```python exec="true" session="quickstart" source="material-block" result="ansi"
+
 # Create nested groups and add arrays
-root = zarr.group("data/example-3.zarr", attributes={'name': 'root'})
+root = zarr.group("data/example-4.zarr", attributes={'name': 'root'})
 foo = root.create_group(name="foo")
 bar = root.create_array(
     name="bar", shape=(100, 10), chunks=(10, 10), dtype="f4"
 )
 nodes = {'': root.metadata} | {k: v.metadata for k,v in root.members()}
 print(nodes)
-from zarr.storage import MemoryStore
-new_nodes = dict(zarr.create_hierarchy(store=MemoryStore(), nodes=nodes))
+new_nodes = dict(zarr.create_hierarchy(store=zarr.storage.MemoryStore(), nodes=nodes))
 new_root = new_nodes['']
 assert new_root.attrs == root.attrs
 ```
@@ -124,6 +119,7 @@ using external libraries like [s3fs](https://s3fs.readthedocs.io) or
 [gcsfs](https://gcsfs.readthedocs.io):
 
 ```python
+
 import s3fs
 
 z = zarr.create_array("s3://example-bucket/foo", mode="w", shape=(100, 100), chunks=(10, 10), dtype="f4")
@@ -132,13 +128,13 @@ z[:, :] = np.random.random((100, 100))
 
 A single-file store can also be created using the `zarr.storage.ZipStore`:
 
-```python
+```python exec="true" session="quickstart" source="material-block"
+
 # Store the array in a ZIP file
-store = zarr.storage.ZipStore("data/example-3.zip", mode='w')
+store = zarr.storage.ZipStore("data/example-5.zip", mode="w")
 
 z = zarr.create_array(
     store=store,
-    mode="w",
     shape=(100, 100),
     chunks=(10, 10),
     dtype="f4"
@@ -153,27 +149,15 @@ store.close()
 
 To open an existing array from a ZIP file:
 
-```python
+```python exec="true" session="quickstart" source="material-block" result="ansi"
+
 # Open the ZipStore in read-only mode
-store = zarr.storage.ZipStore("data/example-3.zip", read_only=True)
+store = zarr.storage.ZipStore("data/example-5.zip", read_only=True)
 
 z = zarr.open_array(store, mode='r')
 
 # read the data as a NumPy Array
-z[:]
-# array([[0.66734236, 0.15667458, 0.98720884, ..., 0.36229587, 0.67443246,
-#         0.34315267],
-#     [0.65787303, 0.9544212 , 0.4830079 , ..., 0.33097172, 0.60423803,
-#         0.45621237],
-#     [0.27632037, 0.9947008 , 0.42434934, ..., 0.94860053, 0.6226942 ,
-#         0.6386924 ],
-#     ...,
-#     [0.12854576, 0.934397  , 0.19524333, ..., 0.11838563, 0.4967675 ,
-#         0.43074256],
-#     [0.82029045, 0.4671437 , 0.8090906 , ..., 0.7814118 , 0.42650765,
-#         0.95929915],
-#     [0.4335856 , 0.7565437 , 0.7828931 , ..., 0.48119593, 0.66220033,
-#         0.6652362 ]], shape=(100, 100), dtype=float32)
+print(z[:])
 ```
 
 Read more about Zarr's storage options in the [User Guide](user-guide/storage.md).

mkdocs.yml

@@ -101,6 +101,7 @@ extra_css:
 
 plugins:
   - search
+  - markdown-exec
   - mkdocstrings:
       enable_inventory: true
       handlers:
@@ -166,3 +167,9 @@ markdown_extensions:
       emoji_generator: !!python/name:material.extensions.emoji.to_svg
   - toc:
       permalink: true
+  - pymdownx.highlight:
+      anchor_linenums: true
+      line_spans: __span
+      pygments_lang_class: true
+  - pymdownx.inlinehilite
+  - pymdownx.snippets