Skip to content

Commit b2ece6f

Browse files
d-v-bd-v-b
authored
docs(zarr-metadata): standalone documentation site; add package justfile (#4208)
* docs(zarr-metadata): add API reference to the docs site 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 * chore(zarr-metadata): add justfile with package-scoped dev recipes 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 * chore(zarr-metadata): make docs-serve robust to a busy port 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 * chore(zarr-metadata): point docs-serve at the package docs, fix cleanup 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 * docs(zarr-metadata): make the package docs a standalone site 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 * update index.md * ci(zarr-metadata): delegate workflow steps to the justfile 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
1 parent bf81831 commit b2ece6f

17 files changed

Lines changed: 514 additions & 12 deletions

File tree

‎.github/workflows/zarr-metadata.yml‎

Lines changed: 34 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,8 @@
11
name: zarr-metadata
22

3+
# Job steps delegate to packages/zarr-metadata/justfile, the single source of
4+
# truth for this package's verbs; CI owns only the python matrix and caching.
5+
36
on:
47
push:
58
branches: [main]
@@ -39,12 +42,14 @@ jobs:
3942
uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
4043
with:
4144
enable-cache: true
45+
- name: Install just
46+
uses: extractions/setup-just@53165ef7e734c5c07cb06b3c8e7b647c5aa16db3 # v4
4247
- name: Set up Python ${{ matrix.python-version }}
4348
run: uv python install ${{ matrix.python-version }}
4449
- name: Sync test dependency group
4550
run: uv sync --group test --python ${{ matrix.python-version }}
4651
- name: Run pytest
47-
run: uv run --group test pytest tests
52+
run: just test
4853

4954
ruff:
5055
name: ruff
@@ -59,8 +64,10 @@ jobs:
5964
persist-credentials: false
6065
- name: Install uv
6166
uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
67+
- name: Install just
68+
uses: extractions/setup-just@53165ef7e734c5c07cb06b3c8e7b647c5aa16db3 # v4
6269
- name: Run ruff
63-
run: uvx ruff check .
70+
run: just lint
6471

6572
pyright:
6673
name: pyright
@@ -77,19 +84,35 @@ jobs:
7784
uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
7885
with:
7986
enable-cache: true
80-
- name: Set up Python
81-
run: uv python install 3.11
82-
- name: Sync test dependency group
83-
run: uv sync --group test --python 3.11
87+
- name: Install just
88+
uses: extractions/setup-just@53165ef7e734c5c07cb06b3c8e7b647c5aa16db3 # v4
8489
- name: Run pyright
85-
# Pinned to the last version that types PEP 661 sentinels in class
86-
# attributes correctly; 1.1.405+ regressed (microsoft/pyright#11115).
87-
# Unpin when the fix lands.
88-
run: uv run --group test --with 'pyright==1.1.404' pyright src
90+
# The pyright version and interpreter pins live in the justfile.
91+
run: just typecheck
92+
93+
docs:
94+
name: docs
95+
runs-on: ubuntu-latest
96+
defaults:
97+
run:
98+
shell: bash
99+
working-directory: packages/zarr-metadata
100+
steps:
101+
- uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
102+
with:
103+
persist-credentials: false
104+
- name: Install uv
105+
uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
106+
with:
107+
enable-cache: true
108+
- name: Install just
109+
uses: extractions/setup-just@53165ef7e734c5c07cb06b3c8e7b647c5aa16db3 # v4
110+
- name: Build docs
111+
run: just docs-check
89112

90113
zarr-metadata-complete:
91114
name: zarr-metadata complete
92-
needs: [test, ruff, pyright]
115+
needs: [test, ruff, pyright, docs]
93116
if: always()
94117
runs-on: ubuntu-latest
95118
steps:

‎mkdocs.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -92,6 +92,7 @@ nav:
9292
- '<code class="doc-symbol doc-symbol-toc doc-symbol-module"></code> <code>zarr.testing.utils</code>': api/zarr/testing/utils.md
9393
- '<code class="doc-symbol doc-symbol-toc doc-symbol-function"></code> <code>zarr.zeros</code>': api/zarr/functions/zeros.md
9494
- '<code class="doc-symbol doc-symbol-toc doc-symbol-function"></code> <code>zarr.zeros_like</code>': api/zarr/functions/zeros_like.md
95+
- 'zarr-metadata ↪': https://zarr-metadata.readthedocs.io/
9596
- release-notes.md
9697
- contributing.md
9798
hooks:

‎packages/zarr-metadata/.readthedocs.yaml‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# Read the Docs configuration for the zarr-metadata docs site, separate from
2+
# the zarr-python site configured by the repo-root .readthedocs.yaml. The RTD
3+
# project for zarr-metadata must set its configuration-file path to
4+
# packages/zarr-metadata/.readthedocs.yaml.
5+
version: 2
6+
7+
build:
8+
os: ubuntu-22.04
9+
tools:
10+
python: "3.12"
11+
jobs:
12+
install:
13+
- pip install --upgrade pip
14+
- pip install ./packages/zarr-metadata --group packages/zarr-metadata/pyproject.toml:docs
15+
build:
16+
html:
17+
- mkdocs build --strict -f packages/zarr-metadata/mkdocs.yml --site-dir $READTHEDOCS_OUTPUT/html
18+
19+
mkdocs:
20+
configuration: packages/zarr-metadata/mkdocs.yml

‎packages/zarr-metadata/README.md‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,8 @@
22

33
Python types, models, and validators for Zarr v2 and v3 metadata.
44

5+
Documentation: <https://zarr-metadata.readthedocs.io/>
6+
57
## What this is
68

79
Two layers and an optional integration:
@@ -82,6 +84,23 @@ store I/O. The models begin and end at the metadata documents themselves —
8284
`from_key_value` / `to_key_value` map documents to store keys and bytes,
8385
and everything past that belongs to consumer libraries.
8486

87+
## Developing
88+
89+
Package-scoped development commands live in the [`justfile`](./justfile)
90+
(requires [just](https://github.com/casey/just)):
91+
92+
```
93+
just test # run the test suite (extra args go to pytest)
94+
just lint # ruff, same invocation as CI
95+
just typecheck # pyright, pinned to the version CI uses
96+
just docs-check # strict build of the docs site
97+
just check # all of the above
98+
just docs-serve # serve the docs site locally
99+
```
100+
101+
Run them from this directory, or from anywhere in the repository as
102+
`just packages/zarr-metadata/<recipe>`.
103+
85104
## Releasing
86105

87106
The package version is derived from git tags by `hatch-vcs`. Tags must

‎packages/zarr-metadata/docs/api/index.md‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
---
2+
title: API reference
3+
---
4+
5+
# API reference
6+
7+
The package is organized to mirror the structure of the Zarr specifications:
8+
9+
- [`zarr_metadata.model`](model.md) — frozen-dataclass document models,
10+
structural validators, loc-aware parsers, and the `UNSET` sentinel
11+
- [`zarr_metadata.pydantic`](pydantic.md) — optional Pydantic field types
12+
over the models
13+
- [`zarr_metadata.v2`](v2.md) — `TypedDict` shapes for Zarr v2 documents
14+
(`.zarray`, `.zgroup`, `.zattrs`, `.zmetadata`)
15+
- [`zarr_metadata.v3`](v3/index.md) — `TypedDict` shapes for Zarr v3
16+
documents, with subpackages for [chunk grids](v3/chunk_grid.md),
17+
[chunk key encodings](v3/chunk_key_encoding.md), [codecs](v3/codec.md),
18+
and [data types](v3/data_type.md)
19+
20+
Every public name is also re-exported at the top level, so
21+
`from zarr_metadata import ZarrV3ArrayMetadataJSON` and
22+
`from zarr_metadata.v3.array import ZarrV3ArrayMetadataJSON` are equivalent.
23+
24+
## Common types
25+
26+
A few cross-cutting aliases are exported only from the top-level
27+
`zarr_metadata` namespace:
28+
29+
::: zarr_metadata.JSONValue
30+
31+
::: zarr_metadata.ZarrV3NamedConfigJSON

‎packages/zarr-metadata/docs/api/model.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
title: model
3+
---
4+
5+
::: zarr_metadata.model

‎packages/zarr-metadata/docs/api/pydantic.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
title: pydantic
3+
---
4+
5+
::: zarr_metadata.pydantic

‎packages/zarr-metadata/docs/api/v2.md‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
---
2+
title: v2
3+
---
4+
5+
::: zarr_metadata.v2
6+
options:
7+
members: false
8+
9+
::: zarr_metadata.v2.array
10+
11+
::: zarr_metadata.v2.group
12+
13+
::: zarr_metadata.v2.attributes
14+
15+
::: zarr_metadata.v2.codec
16+
17+
::: zarr_metadata.v2.consolidated

‎packages/zarr-metadata/docs/api/v3/chunk_grid.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
---
2+
title: chunk_grid
3+
---
4+
5+
::: zarr_metadata.v3.chunk_grid
6+
options:
7+
members: false
8+
9+
::: zarr_metadata.v3.chunk_grid.regular
10+
11+
::: zarr_metadata.v3.chunk_grid.rectilinear

‎packages/zarr-metadata/docs/api/v3/chunk_key_encoding.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
---
2+
title: chunk_key_encoding
3+
---
4+
5+
::: zarr_metadata.v3.chunk_key_encoding
6+
options:
7+
members: false
8+
9+
::: zarr_metadata.v3.chunk_key_encoding.default
10+
11+
::: zarr_metadata.v3.chunk_key_encoding.v2

0 commit comments

Comments
 (0)