Merge branch 'main' into feat/default-buffer

Author: d-v-b

docs/api/zarr/experimental.md

@@ -0,0 +1,9 @@
+---
+title: experimental
+---
+
+Experimental functionality is not stable and may change or be removed at any point.
+
+## Classes
+
+::: zarr.experimental.cache_store

docs/contributing.md

@@ -173,6 +173,40 @@ Hatch can also be used to serve continuously updating version of the documentati
 hatch --env docs run serve
 ```
 
+#### Adding executable code blocks in the documentation
+
+Zarr uses [Markdown Exec](https://pawamoy.github.io/markdown-exec/usage/) to execute code blocks in Markdown files. Add `exec="on"` to a code block header for it to be executed when the docs are built. For example:
+
+````md
+```python exec="on"
+print("Hello world")
+```
+````
+
+Below are other useful options that can be added to the code block. See [Markdown Exec's documentation](https://pawamoy.github.io/markdown-exec/usage/#options-summary) for a full list:
+
+  - `source="above"` makes sure the code within the code block is also rendered in the documentation (rather than just the output).
+  - `session="<name-of-docs-page>"` executes code blocks in a named session reusing previously defined variables.
+  - `result="ansi"` or `result="html"` to render the output. If the code does not produce output, you should leave off the `result` option to prevent an empty cell from rendering in the docs.
+
+For example:
+
+````md
+```python exec="true" session="contributing" source="above" result="ansi"
+print("Hello world")
+```
+````
+
+renders as:
+
+```python exec="true" session="contributing" source="above" result="ansi"
+print("Hello world")
+```
+
+#### Building documentation without executing code blocks
+
+Sometimes, you may want the documentation to build quicker. You can disable code block execution by commenting out the [markdown-exec](https://github.com/zarr-developers/zarr-python/blob/884a8c91afcc3efe28b3da952be3b85125c453cb/mkdocs.yml#L132 plugin in the mkdocs configuration file). This will make code blocks and cross references render incorrectly (i.e., expect build warnings), but also reduces build time by ~3x. Be sure to undo the commenting out before opening your pull request.
+
 ### Changelog
 
 zarr-python uses [towncrier](https://towncrier.readthedocs.io/en/stable/tutorial.html) to manage release notes. Most pull requests should include at least one news fragment describing the changes. To add a release note, you'll need the GitHub issue or pull request number and the type of your change (`feature`, `bugfix`, `doc`, `removal`, `misc`). With that, run `towncrier create` with your development environment, which will prompt you for the issue number, change type, and the news text:

docs/user-guide/experimental.md

@@ -4,7 +4,7 @@ This section contains documentation for experimental Zarr Python features. The f
 
 ## `CacheStore`
 
-Zarr Python 3.1.4 adds `zarr.experimental.cache_store.CacheStore` provides a dual-store caching implementation
+Zarr Python 3.1.4 adds [`zarr.experimental.cache_store.CacheStore`][] provides a dual-store caching implementation
 that can be wrapped around any Zarr store to improve performance for repeated data access.
 This is particularly useful when working with remote stores (e.g., S3, HTTP) where network
 latency can significantly impact data access speed.
@@ -24,7 +24,7 @@ Because the `CacheStore` uses an ordinary Zarr `Store` object as the caching lay
 Creating a CacheStore requires both a source store and a cache store. The cache store
 can be any Store implementation, providing flexibility in cache persistence:
 
-```python exec="true" session="experimental" source="above" result="ansi"
+```python exec="true" session="experimental" source="above"
 import zarr
 from zarr.storage import LocalStore
 import numpy as np
@@ -73,6 +73,7 @@ elapsed_nocache = time.time() - start
 
 # Cache provides speedup for repeated access
 speedup = elapsed_nocache / elapsed_cache
+print(f"Speedup is {speedup}")
 ```
 
 Cache effectiveness is particularly pronounced with repeated access to the same data chunks.
@@ -84,7 +85,7 @@ The CacheStore can be configured with several parameters:
 
 **max_size**: Controls the maximum size of cached data in bytes
 
-```python exec="true" session="experimental" source="above" result="ansi"
+```python exec="true" session="experimental" source="above"
 # 256MB cache with size limit
 cache = CacheStore(
     store=source_store,
@@ -102,7 +103,7 @@ cache = CacheStore(
 
 **max_age_seconds**: Controls time-based cache expiration
 
-```python exec="true" session="experimental" source="above" result="ansi"
+```python exec="true" session="experimental" source="above"
 # Cache expires after 1 hour
 cache = CacheStore(
     store=source_store,
@@ -162,7 +163,7 @@ The `cache_info()` method returns a dictionary with detailed information about t
 
 The CacheStore provides methods for manual cache management:
 
-```python exec="true" session="experimental" source="above" result="ansi"
+```python exec="true" session="experimental" source="above"
 # Clear all cached data and tracking information
 import asyncio
 asyncio.run(cached_store.clear_cache())
@@ -192,7 +193,7 @@ and use any store type for the cache backend:
 
 ### Local Store with Memory Cache
 
-```python exec="true" session="experimental-memory-cache" source="above" result="ansi"
+```python exec="true" session="experimental-memory-cache" source="above"
 from zarr.storage import LocalStore, MemoryStore
 from zarr.experimental.cache_store import CacheStore
 from tempfile import mkdtemp
@@ -209,7 +210,7 @@ cached_store = CacheStore(
 
 ### Memory Store with Persistent Cache
 
-```python exec="true" session="experimental-local-cache" source="above" result="ansi"
+```python exec="true" session="experimental-local-cache" source="above"
 from tempfile import mkdtemp
 from zarr.storage import MemoryStore, LocalStore
 from zarr.experimental.cache_store import CacheStore
@@ -255,10 +256,12 @@ zarr_array[:] = np.random.random((100, 100))
 start = time.time()
 data = zarr_array[20:30, 20:30]  # First access (cache miss)
 first_access = time.time() - start
+print(f"First access took {first_access}")
 
 start = time.time()
 data = zarr_array[20:30, 20:30]  # Second access (cache hit)
 second_access = time.time() - start
+print(f"Second access took {second_access}")
 
 # Check cache statistics
 info = cached_store.cache_info()

mkdocs.yml

@@ -46,6 +46,7 @@ nav:
       - api/zarr/metadata.md
       - api/zarr/registry.md
       - api/zarr/storage.md
+      - api/zarr/experimental.md
       - ABC:
         - api/zarr/abc/index.md
         - api/zarr/abc/buffer.md