docs(zarr-indexing): standalone documentation site; add package justfile

Mirror the treatment zarr-metadata received in zarr-developers#4208/zarr-developers#4210 onto
zarr-indexing: a self-contained mkdocs site under the package (own
mkdocs.yml, landing page, ndsel wire-format guide, mkdocstrings page per
module, and .readthedocs.yaml for a dedicated RTD project), so the
package presents as a separate project with docs versioned by its own
zarr_indexing-v* release tags rather than zarr-python's. The zarr-python
site's API Reference nav links out to it, and each RTD project now skips
PR builds that do not touch its half of the repo.

The package gains a pinned docs dependency group, a docs build job in its
CI workflow, and a justfile with package-scoped dev recipes. Two recipes
deviate from the zarr-metadata original by design:

- `test` runs against the workspace-root environment (`uv run --project
  ../.. --all-packages --group test`), because the chunk-resolution tests
  exercise this package against zarr's chunk grids and `zarr` is
  deliberately not a dependency of this package.
- `typecheck` uses plain `pyright`, unpinned and on the default
  interpreter, mirroring this package's own CI invocation. The
  zarr-metadata pin exists for a PEP 661 sentinel regression that
  zarr-indexing's sources do not hit.

composition.py gains the module docstring the other modules already have,
since mkdocstrings renders it as the page introduction.

Assisted-by: ClaudeCode:claude-fable-5

Author: d-v-b

.github/workflows/zarr-indexing.yml

@@ -87,9 +87,30 @@ jobs:
       - name: Run pyright
         run: uv run --group test --with pyright pyright src
 
+  docs:
+    name: docs
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        shell: bash
+        working-directory: packages/zarr-indexing
+    steps:
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          persist-credentials: false
+      - name: Install uv
+        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+        with:
+          enable-cache: true
+      - name: Install just
+        uses: extractions/setup-just@53165ef7e734c5c07cb06b3c8e7b647c5aa16db3 # v4
+      - name: Build docs
+        # The strict mkdocs build lives in packages/zarr-indexing/justfile.
+        run: just docs-check
+
   zarr-indexing-complete:
     name: zarr-indexing complete
-    needs: [test, ruff, pyright]
+    needs: [test, ruff, pyright, docs]
     if: always()
     runs-on: ubuntu-latest
     steps:

.readthedocs.yaml

@@ -6,15 +6,14 @@ build:
     python: "3.12"
   jobs:
     post_checkout:
-      # Cancel pull request builds whose changes are confined to the
-      # zarr-metadata package, which has its own Read the Docs project. Exit
-      # code 183 cancels the build and reports success to the Git provider.
-      # Scoped to PR builds ("external" versions) because origin/main is only
-      # a meaningful diff base there. Read the Docs strips shell quoting from
-      # commands, so the exclude pathspec must use the quote-free :! form,
-      # not ':(exclude)'.
+      # Cancel pull request builds whose changes are confined to the packages
+      # that have their own Read the Docs projects. Exit code 183 cancels the
+      # build and reports success to the Git provider. Scoped to PR builds
+      # ("external" versions) because origin/main is only a meaningful diff
+      # base there. Read the Docs strips shell quoting from commands, so the
+      # exclude pathspecs must use the quote-free :! form, not ':(exclude)'.
       - |
-        if [ "$READTHEDOCS_VERSION_TYPE" = "external" ] && git diff --quiet origin/main -- :!packages/zarr-metadata;
+        if [ "$READTHEDOCS_VERSION_TYPE" = "external" ] && git diff --quiet origin/main -- :!packages/zarr-metadata :!packages/zarr-indexing;
         then
           exit 183;
         fi

mkdocs.yml

@@ -93,6 +93,7 @@ nav:
       - '<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/
   - release-notes.md
   - contributing.md
 hooks:

packages/zarr-indexing/.readthedocs.yaml

@@ -0,0 +1,30 @@
+# Read the Docs configuration for the zarr-indexing docs site, separate from
+# the zarr-python site configured by the repo-root .readthedocs.yaml. The RTD
+# project for zarr-indexing must set its configuration-file path to
+# packages/zarr-indexing/.readthedocs.yaml.
+version: 2
+
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.12"
+  jobs:
+    post_checkout:
+      # Cancel pull request builds that do not touch this package. Exit code
+      # 183 cancels the build and reports success to the Git provider. Scoped
+      # to PR builds ("external" versions) because origin/main is only a
+      # meaningful diff base there.
+      - |
+        if [ "$READTHEDOCS_VERSION_TYPE" = "external" ] && git diff --quiet origin/main -- packages/zarr-indexing;
+        then
+          exit 183;
+        fi
+    install:
+      - pip install --upgrade pip
+      - pip install ./packages/zarr-indexing --group packages/zarr-indexing/pyproject.toml:docs
+    build:
+      html:
+        - mkdocs build --strict -f packages/zarr-indexing/mkdocs.yml --site-dir $READTHEDOCS_OUTPUT/html
+
+mkdocs:
+  configuration: packages/zarr-indexing/mkdocs.yml

packages/zarr-indexing/README.md

@@ -2,6 +2,8 @@
 
 Composable, lazy coordinate transforms for Zarr array indexing.
 
+Documentation: <https://zarr-indexing.readthedocs.io/>
+
 This package implements TensorStore-inspired index transforms. The core idea:
 every indexing operation (slicing, fancy indexing, etc.) produces a coordinate
 mapping from user space to storage space. These mappings compose lazily — no
@@ -25,6 +27,27 @@ repository and consumed by `zarr` to resolve array indexing operations.
 pip install zarr-indexing
 ```
 
+## Developing
+
+Package-scoped development commands live in the [`justfile`](./justfile)
+(requires [just](https://github.com/casey/just)):
+
+```
+just test        # run the test suite (extra args go to pytest)
+just lint        # ruff, same invocation as CI
+just typecheck   # pyright, same invocation as CI
+just docs-check  # strict build of the docs site
+just check       # all of the above
+just docs-serve  # serve the docs site locally
+```
+
+Run them from this directory, or from anywhere in the repository as
+`just packages/zarr-indexing/<recipe>`.
+
+The test recipe runs against the workspace-root environment, because the
+chunk-resolution tests exercise this package against `zarr`'s chunk grids and
+`zarr` is deliberately not a dependency of this package.
+
 ## License
 
 MIT

packages/zarr-indexing/docs/_static/favicon-96x96.png

@@ -0,0 +1,5 @@
+---
+title: chunk_resolution
+---
+
+::: zarr_indexing.chunk_resolution

packages/zarr-indexing/docs/_static/logo_bw.png

@@ -0,0 +1,5 @@
+---
+title: composition
+---
+
+::: zarr_indexing.composition

packages/zarr-indexing/docs/api/chunk_resolution.md

@@ -0,0 +1,5 @@
+---
+title: domain
+---
+
+::: zarr_indexing.domain