docs: add a page linking to the companion packages

changes/4247.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.

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__](subprojects.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)
 
     ---

docs/subprojects.md

@@ -0,0 +1,35 @@
+# Subprojects
+
+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.
+
+<div class="grid cards" markdown>
+
+- [: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
+    ```
+
+</div>

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
+  - subprojects.md
   - API Reference:
       - api/zarr/index.md
       - '<code class="doc-symbol doc-symbol-toc doc-symbol-module"></code> <code>zarr.abc</code>':
@@ -94,8 +95,12 @@ nav:
         - '<code class="doc-symbol doc-symbol-toc doc-symbol-module"></code> <code>zarr.testing.utils</code>': api/zarr/testing/utils.md
       - '<code class="doc-symbol doc-symbol-toc doc-symbol-function"></code> <code>zarr.zeros</code>': api/zarr/functions/zeros.md
       - '<code class="doc-symbol doc-symbol-toc doc-symbol-function"></code> <code>zarr.zeros_like</code>': 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:

packages/zarr-indexing/mkdocs.yml

@@ -26,6 +26,9 @@ nav:
       - '<code class="doc-symbol doc-symbol-toc doc-symbol-module"></code> <code>zarr_indexing.messages</code>': api/messages.md
       - '<code class="doc-symbol doc-symbol-toc doc-symbol-module"></code> <code>zarr_indexing.errors</code>': 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

packages/zarr-metadata/mkdocs.yml

@@ -25,6 +25,9 @@ nav:
         - '<code class="doc-symbol doc-symbol-toc doc-symbol-module"></code> <code>zarr_metadata.v3.codec</code>': api/v3/codec.md
         - '<code class="doc-symbol doc-symbol-toc doc-symbol-module"></code> <code>zarr_metadata.v3.data_type</code>': 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