Skip to content

docs(zarr-metadata): standalone documentation site; add package justfile - #263

Closed
d-v-b wants to merge 11 commits into
mainfrom
claude/zarr-metadata-api-docs-93fa91
Closed

docs(zarr-metadata): standalone documentation site; add package justfile#263
d-v-b wants to merge 11 commits into
mainfrom
claude/zarr-metadata-api-docs-93fa91

Conversation

@d-v-b

@d-v-b d-v-b commented Jul 29, 2026 •
edited
Loading

Copy link
Copy Markdown
Owner

🤖 AI text below 🤖

Standalone docs site for zarr-metadata

zarr-metadata gets its own mkdocs site under packages/zarr-metadata/, presenting it as a separate package rather than a resource inside the zarr-python docs:

  • docs/index.md — landing page (adapted from the README)
  • docs/api/ — comprehensive API reference (~1,100 documented objects): model, pydantic, v2, and v3 with per-subpackage pages for chunk_grid, chunk_key_encoding, codec (all 9 codecs), and data_type (all 19 dtypes)
  • mkdocs.yml — material theme + mkdocstrings, pinned to the same toolchain versions as the zarr-python site; griffe documents the package from src
  • .readthedocs.yaml — config for a dedicated RTD project (see checklist below)
  • a docs job in the zarr-metadata CI workflow builds the site with --strict

The zarr-python site is untouched except for one external nav link (API Reference → zarr-metadata ↪). The package's Documentation URL now points at https://zarr-metadata.readthedocs.io/. Docs versions will track zarr_metadata-v* tags instead of zarr-python releases.

RTD setup (manual, after merge)

  1. Create a new Read the Docs project (slug zarr-metadata) pointing at this repository.
  2. In the project settings, set the configuration file path to packages/zarr-metadata/.readthedocs.yaml.
  3. Optionally add an automation rule activating versions matching ^zarr_metadata-v.*.

justfile for package-scoped verbs

packages/zarr-metadata/justfile:

  • just test (passthrough args), just lint, just typecheck (pyright pinned to 1.1.404 on python 3.11, matching CI), just docs-check (strict site build), just check (all of the above)
  • just docs-serve — serves the package site; uses port 8000 if free, otherwise falls back to an ephemeral free port (an explicitly requested port fails loudly on conflict)
  • just changelog-draft

Recipes work from the package dir or from the repo root as just packages/zarr-metadata/<recipe>; a future root justfile can namespace them with mod zarr-metadata.

Verification

  • package site: mkdocs build --strict passes (~3 s), all pages render with the expected object counts
  • zarr-python site: mkdocs build --strict, ci/check_documented_exports.py, and ci/lint_docs.py all pass after the revert
  • all justfile recipes run and verified (590 tests pass, pyright clean, ruff clean)
  • pre-commit passes on every changed file

🤖 Generated with Claude Code

d-v-b added 4 commits July 29, 2026 17:54
@d-v-b
fix: fused pipeline falls back for partial-mixin codecs without sync …
80880a0 
…partial methods (zarr-developers#4201)

The partial dispatch in FusedCodecPipeline.read_sync/write_sync asserted
the private _decode_partial_sync/_encode_partial_sync methods, which only
ShardingCodec implements. A codec advertising the public partial mixins
(ArrayBytesCodecPartialDecodeMixin/-EncodeMixin) with only the documented
async partial methods died with a bare AssertionError — or, under
python -O, an AttributeError mid-IO. The asserts are now capability
gates: codecs without the sync partial methods take the full-chunk sync
path instead.

The related crash for sharded arrays with async-only inner codecs is
fixed separately in zarr-developers#4179.

Assisted-by: ClaudeCode:claude-fable-5
@d-v-b
fix: FusedCodecPipeline must apply outer AA/BB codecs on partial paths (
ba83236 
zarr-developers#4202)

FusedCodecPipeline.supports_partial_decode/supports_partial_encode passed
require_no_aa_bb=False, unlike BatchedCodecPipeline (True). With an outer
array-array or bytes-bytes codec around a sharding serializer (e.g.
compressors=[GzipCodec()], or filters=[TransposeCodec()]), the fused
pipeline's partial read/write branches called ShardingCodec's partial
sync methods directly on the raw stored value, skipping those outer
codecs entirely. That wrote non-conforming bytes for an outer BB codec
(unreadable by BatchedCodecPipeline or any conforming reader) and
silently produced wrong data for an outer AA codec.

Pass require_no_aa_bb=True in both fused properties so these chains fall
through to the full-chunk fused path instead, matching batched behavior.

Adds cross-pipeline parity coverage (full and partial read/write) for
sharding with an outer compressor and with an outer transpose filter, and
removes the "known limitation" exclusion that previously kept the
sharding+compressor case out of the nested-sharding parity matrix.

Assisted-by: ClaudeCode:claude-sonnet-5
@d-v-b
docs(zarr-metadata): add API reference to the docs site
560bb92 
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
@d-v-b
chore(zarr-metadata): add justfile with package-scoped dev recipes
00e4289 
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
d-v-b added 3 commits July 29, 2026 18:18
@d-v-b
chore(zarr-metadata): make docs-serve robust to a busy port
3b9c0d9 
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
@d-v-b
chore(zarr-metadata): point docs-serve at the package docs, fix cleanup
ecef99a 
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
@d-v-b
docs(zarr-metadata): make the package docs a standalone site
2a7ecac 
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
@d-v-b d-v-b changed the title docs(zarr-metadata): add API reference; add package justfile docs(zarr-metadata): standalone documentation site; add package justfile Jul 29, 2026
d-v-b added 2 commits July 29, 2026 18:55
@d-v-b
update index.md
1c3b743
@d-v-b
ci(zarr-metadata): delegate workflow steps to the justfile
9c804f5 
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
@d-v-b d-v-b mentioned this pull request Jul 29, 2026
Merged
7 tasks
@d-v-b
docs(zarr-metadata): point the site's repo link at the package directory
deb165d 
The material header source widget linked to the zarr-python repository
root, presenting the site as zarr-python's. Link the package directory
and label it zarr-python/packages/zarr-metadata instead. edit_uri
becomes absolute because mkdocs would append it to repo_url's subpath.

Assisted-by: ClaudeCode:claude-fable-5
@d-v-b

d-v-b commented Jul 29, 2026

Copy link
Copy Markdown
Owner Author

🤖 AI text below 🤖

Merged upstream as zarr-developers#4208. The one commit that landed on this branch after the upstream merge (the docs-site repo-link fix) has been re-based onto current main as #264.

@d-v-b d-v-b closed this Jul 29, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@d-v-b