From 177eb51d3a67f0d30f543ec4bb1d9c11f26b5c2b Mon Sep 17 00:00:00 2001 From: Davis Vann Bennett Date: Tue, 11 Aug 2026 18:29:23 +0200 Subject: [PATCH 1/4] docs: add a page linking to the companion packages The zarr-metadata and zarr-indexing docs are already Read the Docs subprojects of zarr-python and resolve under /projects/, but nothing in the main docs pointed at them except two entries buried at the bottom of the API Reference nav, which linked to the standalone *.readthedocs.io domains rather than the /projects/ paths Read the Docs advertises as canonical. Add a top-level "Related Projects" page listing each companion package, surface it as a card on the landing page, repoint the API Reference nav entries at the canonical subproject URLs, and give each subproject a nav link back to the parent docs. The changelog fragment is named for the issue rather than the PR because the upstream PR number is not known yet; rename it to that number when this is opened upstream. Closes #4246 Assisted-by: ClaudeCode:claude-opus-5 --- changes/4246.doc.md | 5 ++++ docs/index.md | 8 ++++++ docs/projects.md | 44 +++++++++++++++++++++++++++++++ mkdocs.yml | 9 +++++-- packages/zarr-indexing/mkdocs.yml | 3 +++ packages/zarr-metadata/mkdocs.yml | 3 +++ 6 files changed, 70 insertions(+), 2 deletions(-) create mode 100644 changes/4246.doc.md create mode 100644 docs/projects.md diff --git a/changes/4246.doc.md b/changes/4246.doc.md new file mode 100644 index 0000000000..6dbca1d3d6 --- /dev/null +++ b/changes/4246.doc.md @@ -0,0 +1,5 @@ +Added a "Related Projects" page to the documentation listing the companion +packages developed in this repository — `zarr-metadata` and `zarr-indexing` — +and linked it from the landing page. Links to those packages now use the +canonical `https://zarr.readthedocs.io/projects/...` URLs, and each companion +package's documentation links back to the `zarr-python` docs. diff --git a/docs/index.md b/docs/index.md index ee4098a8ea..911970b3fd 100644 --- a/docs/index.md +++ b/docs/index.md @@ -58,6 +58,14 @@ conda install -c conda-forge zarr which parameters can be used. It assumes that you have an understanding of the key concepts. +- [:material-package-variant:{ .lg .middle } __Related projects__](projects.md) + + --- + + Companion packages developed in the zarr-python repository and released + independently, such as `zarr-metadata` and `zarr-indexing`, plus pointers to + the wider Zarr ecosystem. + - [:material-account-group:{ .lg .middle } __Contributor's Guide__](contributing.md) --- diff --git a/docs/projects.md b/docs/projects.md new file mode 100644 index 0000000000..6d21e9f9c8 --- /dev/null +++ b/docs/projects.md @@ -0,0 +1,44 @@ +# Related Projects + +Alongside `zarr` itself, the +[zarr-python repository](https://github.com/zarr-developers/zarr-python) hosts a +small number of companion packages. Each one is developed in the same repository +but versioned, released, and documented independently, so you can depend on it +without taking on `zarr` as a dependency. + +
+ +- [:material-code-json:{ .lg .middle } __zarr-metadata__](https://zarr.readthedocs.io/projects/zarr-metadata/) + + --- + + Spec-defined metadata types, models, and validators for Zarr v2 and v3, with + minimal dependencies. Useful if your software reads or writes Zarr metadata + documents but does not need a full Zarr implementation. + + ```bash + pip install zarr-metadata + ``` + +- [:material-vector-polyline:{ .lg .middle } __zarr-indexing__](https://zarr.readthedocs.io/projects/zarr-indexing/) + + --- + + Composable, lazy coordinate transforms for Zarr array indexing. Makes the + mapping from requested coordinates to stored coordinates a first-class, + composable value, and resolves which chunks a selection touches. + + ```bash + pip install zarr-indexing + ``` + +
+ +## Elsewhere in the Zarr ecosystem + +- [Zarr specifications](https://zarr-specs.readthedocs.io) — the format + specifications that `zarr-python` implements. +- [zarr-extensions](https://github.com/zarr-developers/zarr-extensions/) — the + registry of specified extensions to the Zarr v3 core format. +- [zarr.dev](https://zarr.dev) — the Zarr project website, including + implementations in other languages. diff --git a/mkdocs.yml b/mkdocs.yml index 6a0d94052e..b4af7a72bf 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -33,6 +33,7 @@ nav: - user-guide/examples/rectilinear_chunks.md - user-guide/examples/codec_pipeline_performance.md - user-guide/examples/sharding_coalescing.md + - projects.md - API Reference: - api/zarr/index.md - ' zarr.abc': @@ -94,8 +95,12 @@ nav: - ' zarr.testing.utils': api/zarr/testing/utils.md - ' zarr.zeros': api/zarr/functions/zeros.md - ' zarr.zeros_like': api/zarr/functions/zeros_like.md - - 'zarr-metadata ↪': https://zarr-metadata.readthedocs.io/ - - 'zarr-indexing ↪': https://zarr-indexing.readthedocs.io/ + # The companion packages are Read the Docs subprojects of this one; link + # to the /projects/ paths Read the Docs advertises as canonical rather + # than to their standalone *.readthedocs.io domains, so following one + # keeps the reader on this site's domain. + - 'zarr-metadata ↪': https://zarr.readthedocs.io/projects/zarr-metadata/ + - 'zarr-indexing ↪': https://zarr.readthedocs.io/projects/zarr-indexing/ - release-notes.md - contributing.md - Blog: diff --git a/packages/zarr-indexing/mkdocs.yml b/packages/zarr-indexing/mkdocs.yml index d7261f32e1..43a5ea5b4c 100644 --- a/packages/zarr-indexing/mkdocs.yml +++ b/packages/zarr-indexing/mkdocs.yml @@ -26,6 +26,9 @@ nav: - ' zarr_indexing.messages': api/messages.md - ' zarr_indexing.errors': api/errors.md - Changelog: https://github.com/zarr-developers/zarr-python/blob/main/packages/zarr-indexing/CHANGELOG.md + # This site is a Read the Docs subproject of zarr-python; give readers a way + # back to the parent docs, which list every companion package. + - 'zarr-python ↪': https://zarr.readthedocs.io/ watch: - src diff --git a/packages/zarr-metadata/mkdocs.yml b/packages/zarr-metadata/mkdocs.yml index 6c4a590b3c..18e1fc8c35 100644 --- a/packages/zarr-metadata/mkdocs.yml +++ b/packages/zarr-metadata/mkdocs.yml @@ -25,6 +25,9 @@ nav: - ' zarr_metadata.v3.codec': api/v3/codec.md - ' zarr_metadata.v3.data_type': api/v3/data_type.md - Changelog: https://github.com/zarr-developers/zarr-python/blob/main/packages/zarr-metadata/CHANGELOG.md + # This site is a Read the Docs subproject of zarr-python; give readers a way + # back to the parent docs, which list every companion package. + - 'zarr-python ↪': https://zarr.readthedocs.io/ watch: - src From 567c2ba03cb76bc7493c6ef4f3f3ff92528b2010 Mon Sep 17 00:00:00 2001 From: Davis Bennett Date: Tue, 11 Aug 2026 21:28:40 +0200 Subject: [PATCH 2/4] Rename 4246.doc.md to 4247.doc.md --- changes/{4246.doc.md => 4247.doc.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename changes/{4246.doc.md => 4247.doc.md} (100%) diff --git a/changes/4246.doc.md b/changes/4247.doc.md similarity index 100% rename from changes/4246.doc.md rename to changes/4247.doc.md From c71a620b56d7883765681dfb0ddffc538ed6283b Mon Sep 17 00:00:00 2001 From: Davis Vann Bennett Date: Wed, 12 Aug 2026 09:59:52 +0200 Subject: [PATCH 3/4] docs: projects -> subprojects --- docs/{projects.md => subprojects.md} | 11 +---------- 1 file changed, 1 insertion(+), 10 deletions(-) rename docs/{projects.md => subprojects.md} (72%) diff --git a/docs/projects.md b/docs/subprojects.md similarity index 72% rename from docs/projects.md rename to docs/subprojects.md index 6d21e9f9c8..1903f759d2 100644 --- a/docs/projects.md +++ b/docs/subprojects.md @@ -1,4 +1,4 @@ -# Related Projects +# Subprojects Alongside `zarr` itself, the [zarr-python repository](https://github.com/zarr-developers/zarr-python) hosts a @@ -33,12 +33,3 @@ without taking on `zarr` as a dependency. ``` - -## Elsewhere in the Zarr ecosystem - -- [Zarr specifications](https://zarr-specs.readthedocs.io) — the format - specifications that `zarr-python` implements. -- [zarr-extensions](https://github.com/zarr-developers/zarr-extensions/) — the - registry of specified extensions to the Zarr v3 core format. -- [zarr.dev](https://zarr.dev) — the Zarr project website, including - implementations in other languages. From df3fb338c3f63fa8826e82820e5b4416eb58074e Mon Sep 17 00:00:00 2001 From: Davis Vann Bennett Date: Wed, 12 Aug 2026 10:10:33 +0200 Subject: [PATCH 4/4] docs: rewire docs references correctly --- docs/index.md | 2 +- mkdocs.yml | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/index.md b/docs/index.md index 911970b3fd..eb3b6a5000 100644 --- a/docs/index.md +++ b/docs/index.md @@ -58,7 +58,7 @@ conda install -c conda-forge zarr which parameters can be used. It assumes that you have an understanding of the key concepts. -- [:material-package-variant:{ .lg .middle } __Related projects__](projects.md) +- [:material-package-variant:{ .lg .middle } __Related projects__](subprojects.md) --- diff --git a/mkdocs.yml b/mkdocs.yml index b4af7a72bf..ca8165af4c 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -33,7 +33,7 @@ nav: - user-guide/examples/rectilinear_chunks.md - user-guide/examples/codec_pipeline_performance.md - user-guide/examples/sharding_coalescing.md - - projects.md + - subprojects.md - API Reference: - api/zarr/index.md - ' zarr.abc':