zarr-developers · d-v-b · Nov 20, 2025 · Nov 19, 2025 · Nov 19, 2025 · Nov 19, 2025
diff --git a/docs/api/buffer.md b/docs/api/buffer.md
diff --git a/docs/api/testing.md b/docs/api/testing.md
diff --git a/docs/api/abc/buffer.md → docs/api/zarr/abc/buffer.md b/docs/api/abc/buffer.md → docs/api/zarr/abc/buffer.md
diff --git a/docs/api/abc/codec.md → docs/api/zarr/abc/codec.md b/docs/api/abc/codec.md → docs/api/zarr/abc/codec.md
@@ -3,4 +3,3 @@ title: codec
 ---
 
 ::: zarr.abc.codec
-::: zarr.abc.numcodec
diff --git a/docs/api/zarr/abc/index.md b/docs/api/zarr/abc/index.md
@@ -0,0 +1,7 @@
+## Abstract base classes
+
+- **[buffer](./buffer.md)** - Providing access to underlying memory via [buffers](https://docs.python.org/3/c-api/buffer.html)
+- **[codec](./codec.md)** - Expressing [zarr codecs](https://zarr-specs.readthedocs.io/en/latest/v3/core/index.html#chunk-encoding)
+- **[metadata](./metadata.md)** - Creating metadata classes compatible with the Zarr API
+- **[numcodec](./numcodec.md)** - Protocols and classes for modeling codec interface used by numcodecs
+- **[store](./store.md)** - ABC for implementing Zarr stores and managing getting and setting bytes in a store
diff --git a/docs/api/abc/metadata.md → docs/api/zarr/abc/metadata.md b/docs/api/abc/metadata.md → docs/api/zarr/abc/metadata.md
diff --git a/docs/api/zarr/abc/numcodec.md b/docs/api/zarr/abc/numcodec.md
@@ -0,0 +1,5 @@
+---
+title: numcodec
+---
+
+::: zarr.abc.numcodec
diff --git a/docs/api/abc/store.md → docs/api/zarr/abc/store.md b/docs/api/abc/store.md → docs/api/zarr/abc/store.md
diff --git a/docs/api/api_async.md → docs/api/zarr/api/asynchronous.md b/docs/api/api_async.md → docs/api/zarr/api/asynchronous.md
diff --git a/docs/api/zarr/api/index.md b/docs/api/zarr/api/index.md
@@ -0,0 +1,5 @@
+---
+title: API
+---
+
+Zarr provides both an [async](./asynchronous.md) and a [sync](./synchronous.md) API. See those pages for more details.
diff --git a/docs/api/api_sync.md → docs/api/zarr/api/synchronous.md b/docs/api/api_sync.md → docs/api/zarr/api/synchronous.md
diff --git a/docs/api/array.md → docs/api/zarr/array.md b/docs/api/array.md → docs/api/zarr/array.md
diff --git a/docs/api/zarr/buffer/cpu.md b/docs/api/zarr/buffer/cpu.md
@@ -0,0 +1 @@
+::: zarr.buffer.cpu
diff --git a/docs/api/zarr/buffer/gpu.md b/docs/api/zarr/buffer/gpu.md
@@ -0,0 +1 @@
+::: zarr.buffer.gpu
diff --git a/docs/api/zarr/buffer/index.md b/docs/api/zarr/buffer/index.md
@@ -0,0 +1,3 @@
+Zarr provides buffer classes for both the [cpu](./cpu.md) and [gpu](./gpu.md). Generic buffer functionality is also detailed below.
+
+::: zarr.buffer
diff --git a/docs/api/codecs.md → docs/api/zarr/codecs.md b/docs/api/codecs.md → docs/api/zarr/codecs.md
@@ -3,5 +3,3 @@ title: codecs
 ---
 
 ::: zarr.codecs
-
-::: zarr.codecs.numcodecs
diff --git a/docs/api/zarr/codecs/numcodecs.md b/docs/api/zarr/codecs/numcodecs.md
@@ -0,0 +1,5 @@
+---
+title: numcodecs
+---
+
+::: zarr.codecs.numcodecs
diff --git a/docs/api/config.md → docs/api/zarr/config.md b/docs/api/config.md → docs/api/zarr/config.md
diff --git a/docs/api/convenience.md → docs/api/zarr/convenience.md b/docs/api/convenience.md → docs/api/zarr/convenience.md
diff --git a/docs/api/create.md → docs/api/zarr/create.md b/docs/api/create.md → docs/api/zarr/create.md
diff --git a/docs/api/deprecated/convenience.md → docs/api/zarr/deprecated/convenience.md b/docs/api/deprecated/convenience.md → docs/api/zarr/deprecated/convenience.md
diff --git a/docs/api/deprecated/creation.md → docs/api/zarr/deprecated/creation.md b/docs/api/deprecated/creation.md → docs/api/zarr/deprecated/creation.md
diff --git a/docs/api/dtype.md → docs/api/zarr/dtype.md b/docs/api/dtype.md → docs/api/zarr/dtype.md
diff --git a/docs/api/errors.md → docs/api/zarr/errors.md b/docs/api/errors.md → docs/api/zarr/errors.md
diff --git a/docs/api/group.md → docs/api/zarr/group.md b/docs/api/group.md → docs/api/zarr/group.md
diff --git a/docs/api/index.md → docs/api/zarr/index.md b/docs/api/index.md → docs/api/zarr/index.md
@@ -38,8 +38,8 @@ Complete reference documentation for the Zarr-Python API.
 
 Zarr-Python provides both synchronous and asynchronous APIs:
 
-- **[Async API](api_async.md)** - Asynchronous operations for concurrent access
-- **[Sync API](api_sync.md)** - Synchronous operations for simple usage
+- **[Async API](./api/asynchronous.md)** - Asynchronous operations for concurrent access
+- **[Sync API](./api/synchronous.md)** - Synchronous operations for simple usage
 
 ## Abstract Base Classes
 
@@ -52,7 +52,7 @@ The ABC module defines interfaces for extending Zarr:
 ## Utilities
 
 - **[Errors](errors.md)** - Exception classes and error handling
-- **[Testing](testing.md)** - Utilities for testing Zarr-based code
+- **[Testing](testing/index.md)** - Utilities for testing Zarr-based code
 
 
 ## Migration and Compatibility
@@ -64,7 +64,7 @@ These deprecated modules are maintained for backward compatibility but should be
 
 ## Getting Help
 
-- Check the [User Guide](../user-guide/index.md) for tutorials and examples
+- Check the [User Guide](../../user-guide/index.md) for tutorials and examples
 - Browse function signatures and docstrings in the API reference
 - Report issues on [GitHub](https://github.com/zarr-developers/zarr-python)
 - Join discussions on the [Zarr community forum](https://github.com/zarr-developers/community)
diff --git a/docs/api/load.md → docs/api/zarr/load.md b/docs/api/load.md → docs/api/zarr/load.md
diff --git a/docs/api/metadata.md → docs/api/zarr/metadata.md b/docs/api/metadata.md → docs/api/zarr/metadata.md
diff --git a/docs/api/open.md → docs/api/zarr/open.md b/docs/api/open.md → docs/api/zarr/open.md
diff --git a/docs/api/registry.md → docs/api/zarr/registry.md b/docs/api/registry.md → docs/api/zarr/registry.md
diff --git a/docs/api/save.md → docs/api/zarr/save.md b/docs/api/save.md → docs/api/zarr/save.md
diff --git a/docs/api/storage.md → docs/api/zarr/storage.md b/docs/api/storage.md → docs/api/zarr/storage.md
diff --git a/docs/api/zarr/testing/buffer.md b/docs/api/zarr/testing/buffer.md
@@ -0,0 +1,3 @@
+## Buffer
+
+::: zarr.testing.buffer
diff --git a/docs/api/zarr/testing/conftest.md b/docs/api/zarr/testing/conftest.md
@@ -0,0 +1,3 @@
+## Conftest
+
+::: zarr.testing.conftest
diff --git a/docs/api/zarr/testing/index.md b/docs/api/zarr/testing/index.md
@@ -0,0 +1,12 @@
+---
+title: testing
+---
+
+See the following sub-modules:
+
+- [buffer](./buffer.md)
+- [conftest](./conftest.md)
+- [stateful](./stateful.md)
+- [store](./store.md)
+- [strategies](./strategies.md)
+- [utils](./utils.md)
diff --git a/docs/api/zarr/testing/stateful.md b/docs/api/zarr/testing/stateful.md
@@ -0,0 +1,3 @@
+## Stateful
+
+::: zarr.testing.stateful
diff --git a/docs/api/zarr/testing/store.md b/docs/api/zarr/testing/store.md
@@ -0,0 +1,4 @@
+
+## Store
+
+::: zarr.testing.store
diff --git a/docs/api/zarr/testing/strategies.md b/docs/api/zarr/testing/strategies.md
@@ -0,0 +1,4 @@
+
+## Strategies
+
+::: zarr.testing.strategies
diff --git a/docs/api/zarr/testing/utils.md b/docs/api/zarr/testing/utils.md
@@ -0,0 +1,3 @@
+## Utils
+
+::: zarr.testing.utils
diff --git a/docs/index.md b/docs/index.md
@@ -52,7 +52,7 @@ conda install --channel conda-forge zarr
     A detailed guide for how to use Zarr-Python.
 
 
--   [:material-api:{ .lg .middle } __API Reference__](api/open.md)
+-   [:material-api:{ .lg .middle } __API Reference__](api/zarr/open.md)
 
     ---
 

diff --git a/docs/user-guide/arrays.md b/docs/user-guide/arrays.md
@@ -27,7 +27,7 @@ columns (and so there will be 100 chunks in total). The data is written to a
 and see [Data types](data_types.md) for an in-depth look at the data types supported
 by Zarr.
 
-See the [creation API documentation](../api/create.md) for more detailed information about
+See the [creation API documentation](../api/zarr/create.md) for more detailed information about
 creating arrays.
 
 ## Reading and writing data

diff --git a/docs/user-guide/groups.md b/docs/user-guide/groups.md
@@ -65,12 +65,12 @@ z = root.create_array(name='foo/bar/baz', shape=(10000, 10000), chunks=(1000, 10
 print(z)
 ```
 
-For more information on groups see the [`zarr.Group` API docs](../api/group.md).
+For more information on groups see the [`zarr.Group` API docs](../api/zarr/group.md).
 
 ## Batch Group Creation
 
 You can also create multiple groups concurrently with a single function call. [`zarr.create_hierarchy`][] takes
-a [`zarr Storage instance`](../api/storage.md) instance and a dict of `key : metadata` pairs, parses that dict, and
+a [`zarr Storage instance`](../api/zarr/storage.md) instance and a dict of `key : metadata` pairs, parses that dict, and
 writes metadata documents to storage:
 
 ```python exec="true" session="groups" source="above" result="ansi"

diff --git a/docs/user-guide/index.md b/docs/user-guide/index.md
@@ -37,5 +37,5 @@ Take your skills to the next level:
 
 ## Need Help?
 
-- Browse the [API Reference](../api/index.md) for detailed function documentation
+- Browse the [API Reference](../api/zarr/index.md) for detailed function documentation
 - Report issues on [GitHub](https://github.com/zarr-developers/zarr-python/issues?q=sort%3Aupdated-desc+is%3Aissue+is%3Aopen)
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -30,33 +30,48 @@ nav:
   - Examples:
       - user-guide/examples/custom_dtype.md
   - API Reference:
-      - api/index.md
-      - api/array.md
-      - api/group.md
-      - api/create.md
-      - api/dtype.md
-      - api/open.md
-      - api/load.md
-      - api/save.md
-      - api/buffer.md
-      - api/convenience.md
-      - api/config.md
-      - api/codecs.md
-      - api/errors.md
-      - api/metadata.md
-      - api/registry.md
-      - api/storage.md
-      - api/testing.md
-      - Async API: api/api_async.md
-      - Sync API: api/api_sync.md
+      - api/zarr/index.md
+      - api/zarr/array.md
+      - api/zarr/group.md
+      - api/zarr/create.md
+      - api/zarr/dtype.md
+      - api/zarr/load.md
+      - api/zarr/open.md
+      - api/zarr/save.md
+      - api/zarr/codecs.md
+      - api/zarr/codecs/numcodecs.md
+      - api/zarr/config.md
+      - api/zarr/convenience.md
+      - api/zarr/errors.md
+      - api/zarr/metadata.md
+      - api/zarr/registry.md
+      - api/zarr/storage.md
       - ABC:
-        - api/abc/buffer.md
-        - api/abc/codec.md
-        - api/abc/metadata.md
-        - api/abc/store.md
+        - api/zarr/abc/index.md
+        - api/zarr/abc/buffer.md
+        - api/zarr/abc/codec.md
+        - api/zarr/abc/numcodec.md
+        - api/zarr/abc/metadata.md
+        - api/zarr/abc/store.md
+      - API:
+        - api/zarr/api/index.md
+        - api/zarr/api/asynchronous.md
+        - api/zarr/api/synchronous.md
+      - Buffer:
+        - api/zarr/buffer/index.md
+        - api/zarr/buffer/cpu.md
+        - api/zarr/buffer/gpu.md
+      - Testing:
+        - api/zarr/testing/index.md
+        - api/zarr/testing/buffer.md
+        - api/zarr/testing/conftest.md
+        - api/zarr/testing/stateful.md
+        - api/zarr/testing/store.md
+        - api/zarr/testing/strategies.md
+        - api/zarr/testing/utils.md
       - deprecated:
-        - Convenience sub-module: api/deprecated/convenience.md
-        - Creation sub-module: api/deprecated/creation.md
+        - Convenience sub-module: api/zarr/deprecated/convenience.md
+        - Creation sub-module: api/zarr/deprecated/creation.md
   - release-notes.md
   - contributing.md
 watch:
@@ -197,39 +212,12 @@ plugins:
         'developers/contributing.html.md': 'contributing.md'
         'developers/index.html.md': 'contributing.md'
         'developers/roadmap.html.md': 'https://zarr.readthedocs.io/en/v3.0.8/developers/roadmap.html'
-        'api/zarr/index.html.md': 'api/index.md'
-        'api/zarr/abc/index.html.md': 'api/abc/buffer.md'
-        'api/zarr/abc/buffer/index.html.md': 'api/abc/buffer.md'
-        'api/zarr/abc/codec/index.html.md': 'api/abc/codec.md'
-        'api/zarr/abc/metadata/index.html.md': 'api/abc/metadata.md'
-        'api/zarr/abc/numcodec/index.html.md': 'api/abc/codec.md'
-        'api/zarr/abc/store/index.html.md': 'api/abc/store.md'
-        'api/zarr/api/index.html.md': 'api/index.md'
-        'api/zarr/api/asynchronous/index.html.md': 'api/api_async.md'
-        'api/zarr/api/synchronous/index.html.md': 'api/api_sync.md'
-        'api/zarr/buffer/index.html.md': 'api/buffer.md'
-        'api/zarr/buffer/cpu/index.html.md': 'api/buffer.md'
-        'api/zarr/buffer/gpu/index.html.md': 'api/buffer.md'
-        'api/zarr/codecs/index.html.md': 'api/codecs.md'
-        'api/zarr/codecs/numcodecs/index.html.md': 'api/codecs.md'
-        'api/zarr/convenience/index.html.md': 'api/convenience.md'
-        'api/zarr/creation/index.html.md': 'api/deprecated/creation.md'
-        'api/zarr/dtype/index.html.md': 'api/dtype.md'
-        'api/zarr/errors/index.html.md': 'api/errors.md'
-        'api/zarr/metadata/index.html.md': 'api/metadata.md'
-        'api/zarr/metadata/migrate_v3/index.html.md': 'api/metadata.md'
-        'api/zarr/registry/index.html.md': 'api/registry.md'
-        'api/zarr/storage/index.html.md': 'api/storage.md'
-        'api/zarr/testing/index.html.md': 'api/testing.md'
-        'api/zarr/testing/buffer/index.html.md': 'api/testing.md'
-        'api/zarr/testing/conftest/index.html.md': 'api/testing.md'
-        'api/zarr/testing/stateful/index.html.md': 'api/testing.md'
-        'api/zarr/testing/store/index.html.md': 'api/testing.md'
-        'api/zarr/testing/strategies/index.html.md': 'api/testing.md'
-        'api/zarr/testing/utils/index.html.md': 'api/testing.md'
+        'api/zarr/creation.md': 'api/zarr/deprecated/creation.md'
+        'api/zarr/codecs/numcodecs.md': 'api/zarr/deprecated/creation.md'
+        'api.md': 'api/zarr/index.md'
+        'api/zarr/metadata/migrate_v3.md': 'api/zarr/metadata.md'
 
-
-# https://github.com/developmentseed/titiler/blob/50934c929cca2fa8d3c408d239015f8da429c6a8/docs/mkdocs.yml#L115-L140
+# Based on https://github.com/developmentseed/titiler/blob/50934c929cca2fa8d3c408d239015f8da429c6a8/docs/mkdocs.yml#L115-L140
 markdown_extensions:
   - admonition
   - attr_list
Original file line number	Diff line number	Diff line change
Expand Up		@@ -3,4 +3,3 @@ title: codec
		---

		::: zarr.abc.codec
		::: zarr.abc.numcodec
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,3 @@
		Zarr provides buffer classes for both the [cpu](./cpu.md) and [gpu](./gpu.md). Generic buffer functionality is also detailed below.

		::: zarr.buffer
Original file line number	Diff line number	Diff line change
Expand Up		@@ -3,5 +3,3 @@ title: codecs
		---

		::: zarr.codecs

		::: zarr.codecs.numcodecs
-Original file line number
+Diff line change
@@ Expand Up / @@ -52,7 +52,7 @@ conda install --channel conda-forge zarr @@
         A detailed guide for how to use Zarr-Python.
-    -   [:material-api:{ .lg .middle } __API Reference__](api/open.md)
+    -   [:material-api:{ .lg .middle } __API Reference__](api/zarr/open.md)
         ---
@@ Expand Down @@