diff --git a/docs/api/buffer.md b/docs/api/buffer.md deleted file mode 100644 index aa089957cf..0000000000 --- a/docs/api/buffer.md +++ /dev/null @@ -1,3 +0,0 @@ -::: zarr.buffer -::: zarr.buffer.cpu -::: zarr.buffer.gpu diff --git a/docs/api/testing.md b/docs/api/testing.md deleted file mode 100644 index eef48614b5..0000000000 --- a/docs/api/testing.md +++ /dev/null @@ -1,33 +0,0 @@ ---- -title: testing ---- - -::: zarr.testing - options: - show_root_heading: true - show_root_toc_entry: true - members: false - -## Buffer - -::: zarr.testing.buffer - -## Stateful - -::: zarr.testing.stateful - -## Store - -::: zarr.testing.store - -## Strategies - -::: zarr.testing.strategies - -## Utils - -::: zarr.testing.utils - -## Conftest - -::: zarr.testing.conftest diff --git a/docs/api/abc/buffer.md b/docs/api/zarr/abc/buffer.md similarity index 100% rename from docs/api/abc/buffer.md rename to docs/api/zarr/abc/buffer.md diff --git a/docs/api/abc/codec.md b/docs/api/zarr/abc/codec.md similarity index 65% rename from docs/api/abc/codec.md rename to docs/api/zarr/abc/codec.md index 7d808fbb54..d4eaecabe9 100644 --- a/docs/api/abc/codec.md +++ b/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 new file mode 100644 index 0000000000..7c2fb2ef13 --- /dev/null +++ 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 \ No newline at end of file diff --git a/docs/api/abc/metadata.md b/docs/api/zarr/abc/metadata.md similarity index 100% rename from docs/api/abc/metadata.md rename to docs/api/zarr/abc/metadata.md diff --git a/docs/api/zarr/abc/numcodec.md b/docs/api/zarr/abc/numcodec.md new file mode 100644 index 0000000000..ffbca600cc --- /dev/null +++ b/docs/api/zarr/abc/numcodec.md @@ -0,0 +1,5 @@ +--- +title: numcodec +--- + +::: zarr.abc.numcodec diff --git a/docs/api/abc/store.md b/docs/api/zarr/abc/store.md similarity index 100% rename from docs/api/abc/store.md rename to docs/api/zarr/abc/store.md diff --git a/docs/api/api_async.md b/docs/api/zarr/api/asynchronous.md similarity index 100% rename from docs/api/api_async.md rename to docs/api/zarr/api/asynchronous.md diff --git a/docs/api/zarr/api/index.md b/docs/api/zarr/api/index.md new file mode 100644 index 0000000000..75b4fff62b --- /dev/null +++ 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 b/docs/api/zarr/api/synchronous.md similarity index 100% rename from docs/api/api_sync.md rename to docs/api/zarr/api/synchronous.md diff --git a/docs/api/array.md b/docs/api/zarr/array.md similarity index 100% rename from docs/api/array.md rename to docs/api/zarr/array.md diff --git a/docs/api/zarr/buffer/cpu.md b/docs/api/zarr/buffer/cpu.md new file mode 100644 index 0000000000..9d4726d3ea --- /dev/null +++ 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 new file mode 100644 index 0000000000..e2276d8d82 --- /dev/null +++ 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 new file mode 100644 index 0000000000..0b303781e1 --- /dev/null +++ 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 b/docs/api/zarr/codecs.md similarity index 59% rename from docs/api/codecs.md rename to docs/api/zarr/codecs.md index 151efeac32..c5a0f046ed 100644 --- a/docs/api/codecs.md +++ b/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 new file mode 100644 index 0000000000..ce2a7de145 --- /dev/null +++ b/docs/api/zarr/codecs/numcodecs.md @@ -0,0 +1,5 @@ +--- +title: numcodecs +--- + +::: zarr.codecs.numcodecs diff --git a/docs/api/config.md b/docs/api/zarr/config.md similarity index 100% rename from docs/api/config.md rename to docs/api/zarr/config.md diff --git a/docs/api/convenience.md b/docs/api/zarr/convenience.md similarity index 100% rename from docs/api/convenience.md rename to docs/api/zarr/convenience.md diff --git a/docs/api/create.md b/docs/api/zarr/create.md similarity index 100% rename from docs/api/create.md rename to docs/api/zarr/create.md diff --git a/docs/api/deprecated/convenience.md b/docs/api/zarr/deprecated/convenience.md similarity index 100% rename from docs/api/deprecated/convenience.md rename to docs/api/zarr/deprecated/convenience.md diff --git a/docs/api/deprecated/creation.md b/docs/api/zarr/deprecated/creation.md similarity index 100% rename from docs/api/deprecated/creation.md rename to docs/api/zarr/deprecated/creation.md diff --git a/docs/api/dtype.md b/docs/api/zarr/dtype.md similarity index 100% rename from docs/api/dtype.md rename to docs/api/zarr/dtype.md diff --git a/docs/api/errors.md b/docs/api/zarr/errors.md similarity index 100% rename from docs/api/errors.md rename to docs/api/zarr/errors.md diff --git a/docs/api/group.md b/docs/api/zarr/group.md similarity index 100% rename from docs/api/group.md rename to docs/api/zarr/group.md diff --git a/docs/api/index.md b/docs/api/zarr/index.md similarity index 86% rename from docs/api/index.md rename to docs/api/zarr/index.md index 6160230ac0..f6ae2bda83 100644 --- a/docs/api/index.md +++ b/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 b/docs/api/zarr/load.md similarity index 100% rename from docs/api/load.md rename to docs/api/zarr/load.md diff --git a/docs/api/metadata.md b/docs/api/zarr/metadata.md similarity index 100% rename from docs/api/metadata.md rename to docs/api/zarr/metadata.md diff --git a/docs/api/open.md b/docs/api/zarr/open.md similarity index 100% rename from docs/api/open.md rename to docs/api/zarr/open.md diff --git a/docs/api/registry.md b/docs/api/zarr/registry.md similarity index 100% rename from docs/api/registry.md rename to docs/api/zarr/registry.md diff --git a/docs/api/save.md b/docs/api/zarr/save.md similarity index 100% rename from docs/api/save.md rename to docs/api/zarr/save.md diff --git a/docs/api/storage.md b/docs/api/zarr/storage.md similarity index 100% rename from docs/api/storage.md rename to docs/api/zarr/storage.md diff --git a/docs/api/zarr/testing/buffer.md b/docs/api/zarr/testing/buffer.md new file mode 100644 index 0000000000..e0ae5e5dfd --- /dev/null +++ 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 new file mode 100644 index 0000000000..67cecfd9b8 --- /dev/null +++ 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 new file mode 100644 index 0000000000..4ef56ec69c --- /dev/null +++ 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 new file mode 100644 index 0000000000..53c51b11ec --- /dev/null +++ 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 new file mode 100644 index 0000000000..f190c65f95 --- /dev/null +++ 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 new file mode 100644 index 0000000000..dd6d546165 --- /dev/null +++ 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 new file mode 100644 index 0000000000..61202ac4b2 --- /dev/null +++ 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 index 8508d8e0cf..b61646d6a6 100644 --- 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 index 25a1347fe3..e03b9c9355 100644 --- 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 index 8a3f9ff7bf..57201216b6 100644 --- 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 index 14808457bd..fda9bcaa90 100644 --- 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 index 647f211240..9bc4957f5d 100644 --- 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