docs(zarr-metadata): standalone documentation site; add package justfile - #4208
Merged
d-v-b merged 8 commits intoJul 29, 2026
Merged
Conversation
Add mkdocstrings pages for every public zarr_metadata module (model, pydantic, v2, and v3 with its chunk_grid, chunk_key_encoding, codec, and data_type subpackages) under a new zarr-metadata group in the API Reference nav. griffe documents the package statically from packages/zarr-metadata/src, so the docs build environment does not need the package installed. Point the package's Documentation URL at the rendered reference instead of the README. Assisted-by: ClaudeCode:claude-fable-5
Recipes mirror the zarr-metadata CI jobs (pytest, ruff, pyright pinned to the version CI uses, on CI's python) plus changelog-draft and docs-serve conveniences. Recipes run from the package directory regardless of where just is invoked, and remain reachable from the repo root as 'just packages/zarr-metadata/<recipe>'; a future root justfile can namespace them with a 'mod' declaration. Assisted-by: ClaudeCode:claude-fable-5
With no argument, docs-serve now binds port 8000 if free and otherwise falls back to an ephemeral free port. An explicitly requested port is used as-is so a conflict fails loudly. Assisted-by: ClaudeCode:claude-fable-5
Print the zarr-metadata API reference URL once the server accepts connections, since mkdocs's own 'Serving on' line points at the zarr-python site root. Run the server in its own process group so stopping the recipe kills the whole uv->mkdocs tree instead of leaving an orphaned server holding the port. Assisted-by: ClaudeCode:claude-fable-5
Move the zarr-metadata API reference out of the zarr-python site into a self-contained mkdocs site under packages/zarr-metadata (own mkdocs.yml, landing page, and .readthedocs.yaml for a dedicated RTD project), so the package presents as a separate project with docs versioned by its own zarr_metadata-v* release tags rather than zarr-python's. The zarr-python API Reference nav now links out to the standalone site instead of embedding the pages. The package gains a pinned docs dependency group, a docs build job in its CI workflow, and docs-check / docs-serve justfile recipes targeting the package site. Assisted-by: ClaudeCode:claude-fable-5
The workflow duplicated every command the justfile defines; jobs now run 'just test/lint/typecheck/docs-check' so the justfile is the single source of truth for the package's verbs. CI keeps only its own concerns: the python matrix sync for pytest, and uv caching. The pyright job's python/sync steps are dropped because the typecheck recipe pins the interpreter and pyright version itself. Assisted-by: ClaudeCode:claude-fable-5
github-actions
Bot
added
the
needs release notes
d-v-b
marked this pull request as ready for review
July 29, 2026 17:16
Contributor
Author
|
i'm self-merging when tests pass because I'm the only person who cares about zarr-metadata right now, and this just adds dev tooling / docs |
This was referenced Jul 29, 2026
Closed
d-v-b
added a commit
to d-v-b/zarr-python
that referenced
this pull request
Jul 30, 2026
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
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This PR adds docs for zarr-metadata, and coordinates docs building (and other verbs) with a justfile.
claude wrote it, although I contributed some prose to
index.md. original PR here: d-v-b#263Author attestation
TODO
docs/user-guide/*.mdchanges/