docs/examples (#3502)

* add documentation for examples

* update docs deployment

* fix broken link

* update main examples documentation

* changelog

* Update mkdocs.yml

Co-authored-by: Max Jones <14077947+maxrjones@users.noreply.github.com>

---------

Co-authored-by: Max Jones <14077947+maxrjones@users.noreply.github.com>

Author: d-v-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.

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
 

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"
+```

examples/README.md

@@ -0,0 +1,44 @@
+# 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. 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.:
+
+    ````
+    # 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`)
+- Description of what the example demonstrates
+- Instructions for running the example

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
+```

examples/custom_dtype.py renamed to examples/custom_dtype/custom_dtype.py

@@ -26,6 +26,8 @@ nav:
       - user-guide/gpu.md
       - user-guide/consolidated_metadata.md
       - user-guide/experimental.md
+  - Examples:
+      - user-guide/examples/custom_dtype.md
   - API Reference:
       - api/index.md
       - api/array.md

mkdocs.yml

@@ -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"