document dtype extension

[d-v-b]

This PR adds a working example of custom dtype creation and registration. because it's a lot of code, I put this in a new top-level directory called examples, which contains the executable python file dtype_example.py. This file uses PEP-723 metadata to declare a ml_dtypes dependency, and it uses a local zarr install, which means it can be tested properly against local changes.

I also expanded the current dtype docs in the user guide to include content about the data type resolution process.

TODO:

• [ ] Add unit tests and/or doctests in docstrings
• [ ] Add docstrings and API docs for any new/modified user-facing classes and functions
• [ ] New/modified features documented in docs/user-guide/*.rst
• [ ] Changes documented as a new file in changes/
• [ ] GitHub Actions have all passed
• [ ] Test coverage is 100% (Codecov passes)

[d-v-b]

cc @nenb @ianhi, since yall were the most involved in this example over in the main dtypes PR.

[d-v-b]

I think the content is basically done -- I added docstrings to basically every new class and method (please let me know if i missed anything). I am however currently stymied on some sphinx build issues, so if anyone is proficient in that kind of debugging I would appreciate help.

[d-v-b]

one question for sphinx experts: how can I get sphinx to not mangle the pipe symbol (|), e.g.:

[ianhi]

Build issue is somehow related to this i think:

https://github.com/sphinx-doc/sphinx/issues/12026

https://github.com/readthedocs/sphinx-autoapi/issues/422

[ianhi]

Broken in a new way! Crazy that that fixed that

[d-v-b]

all the sphinx issues are sorted, the only failing check is coverage, and I'm not sure I believe the claims that these changes reduced test coverage by 20%.

[maxrjones]

@d-v-b FYI I think that some of these missing features in 3.0 in the array docs can now instead be linked to the new dtypes docs - https://zarr.readthedocs.io/en/stable/user-guide/arrays.html#missing-features-in-3-0.

[d-v-b]

@d-v-b FYI I think that some of these missing features in 3.0 in the array docs can now instead be linked to the new dtypes docs - https://zarr.readthedocs.io/en/stable/user-guide/arrays.html#missing-features-in-3-0.

I removed the "this stuff is missing" sections, leaving only the part that is still missing (the copying + migrating data stuff)