add documentation for examples

Author: d-v-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"
+```

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.

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