Repository navigation
docs: show package tag instead of monorepo release in subpackage docs - #4229
Merged
d-v-b merged 9 commits intoSep 25, 2026
Merged
Conversation
github-actions
Bot
added
the
needs release notes
Contributor
|
this is awesome max! short term i'm leaning anti DRY (pro duplication) but longer term this is something our docs dep should handle without modifications. we should investigate upstreaming this fix |
Member
Author
thanks for the prompt feedback. I consolidated both the patch script and the mkdocs configuration files. |
maxrjones
commented
Aug 3, 2026
maxrjones
commented
Aug 3, 2026
d-v-b
reviewed
Aug 3, 2026
d-v-b
reviewed
Aug 3, 2026
…l sites Resolve conflicts with main: keep main's zarr-indexing uv.lock, and move main's newer per-package config (release notes nav, parent-docs link, snippets, content tabs, validation) onto the shared INHERIT base. INHERIT replaces lists rather than merging them, so the base carries the superset of theme features and markdown extensions (pymdownx.tabbed, content.tabs.link, snippets with base_path [docs, examples, .]). Migrate zarr-http-server onto the base and link source-version.js into its docs, so its header shows zarr_http_server tags too. Skip pre-release tags in source-version.js: 0.5.0rc1 parsed as 0.5.0 and, given the tags API's reverse-lexicographic order, won the tie. Assisted-by: ClaudeCode:claude-opus-5-5
Contributor
|
this needs some minor conflict resolution, and a few other changes, see maxrjones/zarr-python@docs/subpackage-header-version...d-v-b:zarr-python:docs/subpackage-header-version-fixes lmk if it's OK to push to this branch? |
Member
Author
yes, totally fine |
…ile changes
The docs/_static/source-version.js symlink points outside the package, so
each sdist carried a dangling link and pip refused to unpack it ("would
link to ... outside the destination"). mkdocs.yml's INHERIT of
../mkdocs-base.yml likewise broke `mkdocs build` from an unpacked sdist.
Link mkdocs-base.yml into each package too, INHERIT it from the package
directory, and have the sdists exclude both links and force-include the
files they point at. The sdist is self-contained again.
Package CI and the RTD PR-build skip only watched packages/<name>, so an
edit to the shared base or script built no site. Add both shared files to
every package workflow's paths and to each .readthedocs.yaml diff.
Assisted-by: ClaudeCode:claude-opus-5-5
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #4229 +/- ##
=======================================
Coverage 94.37% 94.37%
=======================================
Files 93 93
Lines 13171 13171
=======================================
Hits 12430 12430
Misses 741 741 🚀 New features to boost your workflow:
|
The three sites share packages/mkdocs-base.yml but resolved different plugin versions (mkdocstrings 1.0.4 vs 1.0.6, mkdocstrings-python 2.0.5, ruff 0.15.20 / 0.15.22 / 0.16.0), and two packages' comments claimed to match the root docs group while not doing so. Pin all three to the root's versions (mkdocstrings 1.0.6, mkdocstrings-python 2.0.8, ruff 0.16.8) and relock zarr-indexing and zarr-http-server. Assisted-by: ClaudeCode:claude-opus-5-5
Contributor
|
this setup will prevent us from rebuilding an sdist from an sdist, but I'm ranking that "niche" and approving. thanks for this @maxrjones! |
d-v-b
approved these changes
Sep 25, 2026
d-v-b
added a commit
to d-v-b/zarr-python
that referenced
this pull request
Sep 25, 2026
`hatch build` builds the wheel from the source tree, so nothing exercised the sdist: zarr-developers#4229's first cut shipped sdists whose symlinks pip refuses to unpack, and the release workflows would have uploaded them. The test_artifacts job now builds a wheel from the sdist with pip, then runs the package's `just test` and `just docs-check` from the unpacked sdist. The job has no checkout, so zarr (for zarr-http-server) resolves from PyPI, which also covers the `zarr>=3.1` floor that repo runs, overlaying in-repo zarr, never check. Assisted-by: ClaudeCode:claude-opus-5-5
d-v-b
added a commit
to d-v-b/zarr-python
that referenced
this pull request
Sep 25, 2026
…pers#4229 Assisted-by: ClaudeCode:claude-opus-5-5
This was referenced Sep 25, 2026
d-v-b
added a commit
to d-v-b/zarr-python
that referenced
this pull request
Sep 25, 2026
`hatch build` builds the wheel from the source tree, so nothing exercised the sdist: zarr-developers#4229's first cut shipped sdists whose symlinks pip refuses to unpack, and the release workflows would have uploaded them. The test_artifacts job now builds a wheel from the sdist with pip, then runs the package's `just test` and `just docs-check` from the unpacked sdist. The job has no checkout, so zarr (for zarr-http-server) resolves from PyPI, which also covers the `zarr>=3.1` floor that repo runs, overlaying in-repo zarr, never check. Assisted-by: ClaudeCode:claude-opus-5-5
d-v-b
added a commit
to d-v-b/zarr-python
that referenced
this pull request
Sep 25, 2026
…pers#4229 Assisted-by: ClaudeCode:claude-opus-5-5
d-v-b
added a commit
that referenced
this pull request
Sep 25, 2026
…m guidance (#4407) * chore: keep sub-package pyproject.toml standalone; overlay in-repo zarr from just The packages reached in-repo zarr two different ways: zarr-http-server pinned it with `[tool.uv.sources] zarr = { path = "../.." }` in pyproject.toml, and zarr-indexing ran its tests in the repo root's environment (`uv run --project ../..`). Both reach outside the package, so neither package's unpacked sdist could run its own `just test`. Now every package's pyproject.toml stands alone, and the justfiles add the in-repo zarr as an editable overlay (`--with-editable ../..`) only when ../.. is the repository. From an sdist there is no overlay: zarr-http-server resolves zarr from PyPI, and zarr-indexing's zarr suites skip. zarr-metadata needs no zarr and is unchanged. zarr-http-server's uv.lock now resolves zarr from PyPI, and zarr-indexing CI syncs the package environment instead of the root one. Assisted-by: ClaudeCode:claude-opus-5-5 * chore: add changelog fragments for #4406 Assisted-by: ClaudeCode:claude-opus-5-5 * build: replace deprecated git_describe_command; commit zarr-metadata uv.lock setuptools-scm deprecates the top-level `git_describe_command` in favour of `scm.git.describe_command` (a DeprecationWarning builds swallow). Move the root and all three sub-packages to the new key; hatch-vcs passes raw-options to setuptools_scm.get_version, which accepts `scm` from setuptools-scm 9.0 (8.4, which the docs name, was never released), so require setuptools-scm>=9 at build time. Computed versions are unchanged. `tag.prefix`, setuptools-scm's documented monorepo option, is not reachable through hatch-vcs 0.5.0: get_version() takes no `tag` argument. uv's docs say uv.lock "should be checked into version control", with no library exception, and the other two sub-packages already commit theirs. Stop ignoring zarr-metadata's. Assisted-by: ClaudeCode:claude-opus-5-5 * ci: test each sub-package sdist standalone before release `hatch build` builds the wheel from the source tree, so nothing exercised the sdist: #4229's first cut shipped sdists whose symlinks pip refuses to unpack, and the release workflows would have uploaded them. The test_artifacts job now builds a wheel from the sdist with pip, then runs the package's `just test` and `just docs-check` from the unpacked sdist. The job has no checkout, so zarr (for zarr-http-server) resolves from PyPI, which also covers the `zarr>=3.1` floor that repo runs, overlaying in-repo zarr, never check. Assisted-by: ClaudeCode:claude-opus-5-5 * chore: add changelog fragment for #363 Assisted-by: ClaudeCode:claude-opus-5-5 * chore(zarr-metadata): relock for the docs pins aligned in #4229 Assisted-by: ClaudeCode:claude-opus-5-5 * chore: renumber changelog fragment for #4407 Assisted-by: ClaudeCode:claude-opus-5-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
2 participants
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.
Summary
This PR patches mkdocs to use the subpackage's tag instead of Zarr-Python core's in the docs header.
For reviewers
Opinions on whether we should duplicate the patch on each sub-package (anti-DRY) or symlink (anti-windows).
Author attestation
TODO
docs/user-guide/*.mdchanges/