From ca4caa77b8f05b962ac45f2b25eae10444e64164 Mon Sep 17 00:00:00 2001 From: Davis Vann Bennett Date: Thu, 2 Oct 2025 13:24:05 +0200 Subject: [PATCH 1/6] add documentation for examples --- docs/user-guide/examples/custom_dtype.md | 7 ++++ examples/README.md | 38 +++++++++++++++++++++ examples/custom_dtype/README.md | 22 ++++++++++++ examples/{ => custom_dtype}/custom_dtype.py | 0 4 files changed, 67 insertions(+) create mode 100644 docs/user-guide/examples/custom_dtype.md create mode 100644 examples/README.md create mode 100644 examples/custom_dtype/README.md rename examples/{ => custom_dtype}/custom_dtype.py (100%) diff --git a/docs/user-guide/examples/custom_dtype.md b/docs/user-guide/examples/custom_dtype.md new file mode 100644 index 0000000000..d6736e25dd --- /dev/null +++ b/docs/user-guide/examples/custom_dtype.md @@ -0,0 +1,7 @@ +--8<-- "examples/custom_dtype/README.md" + +## Source Code + +```python +--8<-- "examples/custom_dtype/custom_dtype.py" +``` diff --git a/examples/README.md b/examples/README.md new file mode 100644 index 0000000000..0bd6d8db82 --- /dev/null +++ b/examples/README.md @@ -0,0 +1,38 @@ +# Zarr Python Examples + +This directory contains complete, runnable examples demonstrating various features and use cases of Zarr Python. + +## Directory Structure + +Each example is organized in its own subdirectory with the following structure: + +``` +examples/ +├── example_name/ +│ ├── README.md # Documentation for the example +│ └── example_name.py # Python source code +└── ... +``` + +## Adding New Examples + +To add a new example: + +1. Create a new subdirectory: `examples/my_example/` +2. Add your Python code: `examples/my_example/my_example.py` +3. Create documentation: `examples/my_example/README.md` +4. Run the documentation generator: `python3 scripts/generate_examples_docs.py` + +The documentation generator will automatically: +- Create a documentation page at `docs/user-guide/examples/my_example.md` +- Update `mkdocs.yml` to include the new example in the navigation + +### Example README.md Format + +Your README.md should include: + +- A title (# Example Name) +- Description of what the example demonstrates +- Instructions for running the example + +**Note:** The source code will be automatically appended to the documentation when you run the generator script. diff --git a/examples/custom_dtype/README.md b/examples/custom_dtype/README.md new file mode 100644 index 0000000000..c0722d0661 --- /dev/null +++ b/examples/custom_dtype/README.md @@ -0,0 +1,22 @@ +# Custom Data Type Example + +This example demonstrates how to extend Zarr Python by defining a new data type. + +The example shows how to: + +- Define a custom `ZDType` class for the `int2` data type from [`ml_dtypes`](https://pypi.org/project/ml-dtypes/) +- Implement all required methods for serialization and deserialization +- Register the custom data type with Zarr's registry +- Create and use arrays with the custom data type in both Zarr v2 and v3 formats + +## Running the Example + +```bash +python examples/custom_dtype/custom_dtype.py +``` + +Or run with uv: + +```bash +uv run examples/custom_dtype/custom_dtype.py +``` diff --git a/examples/custom_dtype.py b/examples/custom_dtype/custom_dtype.py similarity index 100% rename from examples/custom_dtype.py rename to examples/custom_dtype/custom_dtype.py From 7017adbfc5db3d998e790fd9c288303a9b8de446 Mon Sep 17 00:00:00 2001 From: Davis Vann Bennett Date: Thu, 2 Oct 2025 13:24:24 +0200 Subject: [PATCH 2/6] update docs deployment --- mkdocs.yml | 2 ++ pyproject.toml | 2 +- 2 files changed, 3 insertions(+), 1 deletion(-) diff --git a/mkdocs.yml b/mkdocs.yml index 53b8eef7d4..bc4cc7621b 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -25,6 +25,8 @@ nav: - user-guide/extending.md - user-guide/gpu.md - user-guide/consolidated_metadata.md + - Examples: + - user-guide/examples/custom_dtype.md - API Reference: - api/index.md - api/array.md diff --git a/pyproject.toml b/pyproject.toml index 6164f69382..e727274fba 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -251,7 +251,7 @@ dependencies = [ features = ['docs', 'remote'] [tool.hatch.envs.docs.scripts] -serve = "mkdocs serve" +serve = "mkdocs serve --watch src" build = "mkdocs build" check = "mkdocs build --strict" readthedocs = "rm -rf $READTHEDOCS_OUTPUT/html && cp -r site $READTHEDOCS_OUTPUT/html" From 5835756e48413df0c346b37cd17688c9806cc0ee Mon Sep 17 00:00:00 2001 From: Davis Vann Bennett Date: Thu, 2 Oct 2025 13:29:46 +0200 Subject: [PATCH 3/6] fix broken link --- docs/user-guide/data_types.md | 10 ++-------- 1 file changed, 2 insertions(+), 8 deletions(-) diff --git a/docs/user-guide/data_types.md b/docs/user-guide/data_types.md index 82b7c89809..aa19baf891 100644 --- a/docs/user-guide/data_types.md +++ b/docs/user-guide/data_types.md @@ -298,14 +298,8 @@ assert scalar_value == np.int8(42) Each Zarr data type is a separate Python class that inherits from [ZDType][zarr.dtype.ZDType]. You can define a custom data type by writing your own subclass of [ZDType][zarr.dtype.ZDType] and adding -your data type to the data type registry. A complete example of this process is included below. - -The source code for this example can be found in the `examples/custom_dtype.py` file in the Zarr -Python project directory. - -```python ---8<-- "examples/custom_dtype.py" -``` +your data type to the data type registry. To see an executable demonstration +of this process, see the [`custom_dtype` example](../user-guide/examples/custom_dtype.md). ### Data Type Resolution From 5da3243f7a295cd72e4714d1672742d7bf83050d Mon Sep 17 00:00:00 2001 From: Davis Vann Bennett Date: Thu, 2 Oct 2025 13:39:52 +0200 Subject: [PATCH 4/6] update main examples documentation --- examples/README.md | 20 +++++++++++++------- 1 file changed, 13 insertions(+), 7 deletions(-) diff --git a/examples/README.md b/examples/README.md index 0bd6d8db82..a6b5fa2179 100644 --- a/examples/README.md +++ b/examples/README.md @@ -21,18 +21,24 @@ To add a new example: 1. Create a new subdirectory: `examples/my_example/` 2. Add your Python code: `examples/my_example/my_example.py` 3. Create documentation: `examples/my_example/README.md` -4. Run the documentation generator: `python3 scripts/generate_examples_docs.py` +4. Create a documentation page at `docs/user-guide/examples/my_example.md`. The documentation page should simply link to the `README.md` and the source code, e.g.: -The documentation generator will automatically: -- Create a documentation page at `docs/user-guide/examples/my_example.md` -- Update `mkdocs.yml` to include the new example in the navigation + ```` + # docs/user-guide/examples/my_example.md + --8<-- "examples/my_example/README.md" + + ## Source Code + + ```python + --8<-- "examples/my_example/my_example.py" + ``` + ```` +5. Update `mkdocs.yml` to include the new example in the navigation. ### Example README.md Format Your README.md should include: -- A title (# Example Name) +- A title (`# Example Name`) - Description of what the example demonstrates - Instructions for running the example - -**Note:** The source code will be automatically appended to the documentation when you run the generator script. From f78b09f9bdad468a1679020db8404d02de623886 Mon Sep 17 00:00:00 2001 From: Davis Vann Bennett Date: Thu, 2 Oct 2025 13:51:17 +0200 Subject: [PATCH 5/6] changelog --- changes/3502.doc.md | 1 + 1 file changed, 1 insertion(+) create mode 100644 changes/3502.doc.md diff --git a/changes/3502.doc.md b/changes/3502.doc.md new file mode 100644 index 0000000000..031c046bf4 --- /dev/null +++ b/changes/3502.doc.md @@ -0,0 +1 @@ +Reorganize the top-level `examples` directory to give each example its own sub-directory. Adds content to the docs for each example. \ No newline at end of file From e4054ad9e78630cfca05a88f90dc86247100e2dc Mon Sep 17 00:00:00 2001 From: Davis Bennett Date: Thu, 2 Oct 2025 20:19:10 +0200 Subject: [PATCH 6/6] Update mkdocs.yml Co-authored-by: Max Jones <14077947+maxrjones@users.noreply.github.com> --- mkdocs.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/mkdocs.yml b/mkdocs.yml index 78c457cd90..c9edf338af 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -25,9 +25,9 @@ nav: - user-guide/extending.md - user-guide/gpu.md - user-guide/consolidated_metadata.md - - Examples: - - user-guide/examples/custom_dtype.md - user-guide/experimental.md + - Examples: + - user-guide/examples/custom_dtype.md - API Reference: - api/index.md - api/array.md