From 13e134c4e8d46899902b4dce2fe4b9930b73e388 Mon Sep 17 00:00:00 2001 From: Davis Vann Bennett Date: Wed, 21 Oct 2026 13:22:54 +0200 Subject: [PATCH 1/2] ci(docs): fix the Read the Docs sub-site builds and skip filters The zarr-indexing, zarr-metadata and zarr-http-server docs sites install their docs group with pip on Read the Docs, without a lockfile, so pymdown-extensions floated to 12.3, whose Highlight extension API the pinned mkdocstrings 1.0.6 cannot drive (Highlight.__init__() missing argument 'md'). No zarr-indexing build has succeeded since. Pin pymdown-extensions to 11.0.1, the version the repo-root uv.lock resolves to, and refresh the package lockfiles. The post_checkout skip filters compared the PR head against the tip of main with a two-dot diff, so any PR that was behind main appeared to touch every package and built every site. Compare against the merge base instead, after fetching full history into the shallow checkout. Also exclude zarr-http-server from the root site's filter, as the other two packages already were. Assisted-by: ClaudeCode:claude-fable-5.1 Co-Authored-By: Claude Fable 5.1 --- .readthedocs.yaml | 21 ++++++++++++++++++--- packages/zarr-http-server/.readthedocs.yaml | 14 ++++++++++++-- packages/zarr-http-server/pyproject.toml | 4 ++++ packages/zarr-http-server/uv.lock | 2 ++ packages/zarr-indexing/.readthedocs.yaml | 14 ++++++++++++-- packages/zarr-indexing/pyproject.toml | 4 ++++ packages/zarr-indexing/uv.lock | 2 ++ packages/zarr-metadata/.readthedocs.yaml | 14 ++++++++++++-- packages/zarr-metadata/pyproject.toml | 4 ++++ packages/zarr-metadata/uv.lock | 8 +++++--- 10 files changed, 75 insertions(+), 12 deletions(-) diff --git a/.readthedocs.yaml b/.readthedocs.yaml index 872eb2be80..d079f62d5a 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -10,12 +10,27 @@ build: # 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 + # base there. Compare against the merge base (origin/main...HEAD), not + # against the tip of main: a two-dot diff also reports everything that + # landed on main after the PR branched, which made every PR that was + # behind main build every site. The checkout is shallow, so fetch the + # full history first; without a merge base the diff fails and the build + # runs, which is the safe default. Read the Docs strips shell quoting from commands, so the # exclude pathspecs must use the quote-free :! form, not ':(exclude)'. + # The diff is taken against the merge base (origin/main...HEAD), not + # against the tip of main: a two-dot diff also reports everything that + # landed on main after the PR branched, which made every PR that was + # behind main build every site. The checkout is shallow, so fetch the + # full history first; without a merge base the diff fails and the build + # runs, which is the safe default. - | - if [ "$READTHEDOCS_VERSION_TYPE" = "external" ] && git diff --quiet origin/main -- :!packages/zarr-metadata :!packages/zarr-indexing; + if [ "$READTHEDOCS_VERSION_TYPE" = "external" ]; then - exit 183; + git fetch --quiet --unshallow origin main pull/$READTHEDOCS_VERSION_NAME/head || true; + if git diff --quiet origin/main...HEAD -- :!packages/zarr-metadata :!packages/zarr-indexing :!packages/zarr-http-server; + then + exit 183; + fi fi install: - pip install --upgrade pip diff --git a/packages/zarr-http-server/.readthedocs.yaml b/packages/zarr-http-server/.readthedocs.yaml index 09cf295794..4490a0c3e1 100644 --- a/packages/zarr-http-server/.readthedocs.yaml +++ b/packages/zarr-http-server/.readthedocs.yaml @@ -15,10 +15,20 @@ build: # to PR builds ("external" versions) because origin/main is only a # meaningful diff base there. The shared docs config and header script # live outside the package directory but change this site too. + # The diff is taken against the merge base (origin/main...HEAD), not + # against the tip of main: a two-dot diff also reports everything that + # landed on main after the PR branched, which made every PR that was + # behind main build every site. The checkout is shallow, so fetch the + # full history first; without a merge base the diff fails and the build + # runs, which is the safe default. - | - if [ "$READTHEDOCS_VERSION_TYPE" = "external" ] && git diff --quiet origin/main -- packages/zarr-http-server packages/mkdocs-base.yml packages/source-version.js; + if [ "$READTHEDOCS_VERSION_TYPE" = "external" ]; then - exit 183; + git fetch --quiet --unshallow origin main pull/$READTHEDOCS_VERSION_NAME/head || true; + if git diff --quiet origin/main...HEAD -- packages/zarr-http-server packages/mkdocs-base.yml packages/source-version.js; + then + exit 183; + fi fi install: - pip install --upgrade pip diff --git a/packages/zarr-http-server/pyproject.toml b/packages/zarr-http-server/pyproject.toml index 1d312cf93f..f7a46eda90 100644 --- a/packages/zarr-http-server/pyproject.toml +++ b/packages/zarr-http-server/pyproject.toml @@ -70,6 +70,10 @@ docs = [ "mkdocs-material==9.7.7", "mkdocs==1.6.1", "mkdocstrings==1.0.6", + # pymdown-extensions 12.3 changed the Highlight extension API; mkdocstrings 1.0.6 + # cannot drive it (Highlight.__init__() missing argument "md"). Match the + # version in the repo-root uv.lock until mkdocstrings is bumped everywhere. + "pymdown-extensions==11.0.1", "mkdocstrings-python==2.0.8", "griffe-inherited-docstrings==1.1.3", # mkdocstrings uses ruff to format rendered signatures diff --git a/packages/zarr-http-server/uv.lock b/packages/zarr-http-server/uv.lock index 673dc54645..77bb5a0baf 100644 --- a/packages/zarr-http-server/uv.lock +++ b/packages/zarr-http-server/uv.lock @@ -2156,6 +2156,7 @@ docs = [ { name = "mkdocs-material" }, { name = "mkdocstrings" }, { name = "mkdocstrings-python" }, + { name = "pymdown-extensions" }, { name = "ruff" }, ] examples = [ @@ -2186,6 +2187,7 @@ docs = [ { name = "mkdocs-material", specifier = "==9.7.7" }, { name = "mkdocstrings", specifier = "==1.0.6" }, { name = "mkdocstrings-python", specifier = "==2.0.8" }, + { name = "pymdown-extensions", specifier = "==11.0.1" }, { name = "ruff", specifier = "==0.16.8" }, ] examples = [ diff --git a/packages/zarr-indexing/.readthedocs.yaml b/packages/zarr-indexing/.readthedocs.yaml index 4228d267ca..6577440275 100644 --- a/packages/zarr-indexing/.readthedocs.yaml +++ b/packages/zarr-indexing/.readthedocs.yaml @@ -15,10 +15,20 @@ build: # to PR builds ("external" versions) because origin/main is only a # meaningful diff base there. The shared docs config and header script # live outside the package directory but change this site too. + # The diff is taken against the merge base (origin/main...HEAD), not + # against the tip of main: a two-dot diff also reports everything that + # landed on main after the PR branched, which made every PR that was + # behind main build every site. The checkout is shallow, so fetch the + # full history first; without a merge base the diff fails and the build + # runs, which is the safe default. - | - if [ "$READTHEDOCS_VERSION_TYPE" = "external" ] && git diff --quiet origin/main -- packages/zarr-indexing packages/mkdocs-base.yml packages/source-version.js; + if [ "$READTHEDOCS_VERSION_TYPE" = "external" ]; then - exit 183; + git fetch --quiet --unshallow origin main pull/$READTHEDOCS_VERSION_NAME/head || true; + if git diff --quiet origin/main...HEAD -- packages/zarr-indexing packages/mkdocs-base.yml packages/source-version.js; + then + exit 183; + fi fi install: - pip install --upgrade pip diff --git a/packages/zarr-indexing/pyproject.toml b/packages/zarr-indexing/pyproject.toml index da7bee34aa..50a63832ea 100644 --- a/packages/zarr-indexing/pyproject.toml +++ b/packages/zarr-indexing/pyproject.toml @@ -61,6 +61,10 @@ docs = [ "mkdocs-material==9.7.7", "mkdocs==1.6.1", "mkdocstrings==1.0.6", + # pymdown-extensions 12.3 changed the Highlight extension API; mkdocstrings 1.0.6 + # cannot drive it (Highlight.__init__() missing argument "md"). Match the + # version in the repo-root uv.lock until mkdocstrings is bumped everywhere. + "pymdown-extensions==11.0.1", "mkdocstrings-python==2.0.8", "griffe-inherited-docstrings==1.1.3", # mkdocstrings uses ruff to format rendered signatures diff --git a/packages/zarr-indexing/uv.lock b/packages/zarr-indexing/uv.lock index 1a4a90e2ba..37a98a5694 100644 --- a/packages/zarr-indexing/uv.lock +++ b/packages/zarr-indexing/uv.lock @@ -740,6 +740,7 @@ docs = [ { name = "mkdocs-material" }, { name = "mkdocstrings" }, { name = "mkdocstrings-python" }, + { name = "pymdown-extensions" }, { name = "ruff" }, ] test = [ @@ -761,6 +762,7 @@ docs = [ { name = "mkdocs-material", specifier = "==9.7.7" }, { name = "mkdocstrings", specifier = "==1.0.6" }, { name = "mkdocstrings-python", specifier = "==2.0.8" }, + { name = "pymdown-extensions", specifier = "==11.0.1" }, { name = "ruff", specifier = "==0.16.8" }, ] test = [ diff --git a/packages/zarr-metadata/.readthedocs.yaml b/packages/zarr-metadata/.readthedocs.yaml index b67e76948c..5e6f993a3e 100644 --- a/packages/zarr-metadata/.readthedocs.yaml +++ b/packages/zarr-metadata/.readthedocs.yaml @@ -15,10 +15,20 @@ build: # to PR builds ("external" versions) because origin/main is only a # meaningful diff base there. The shared docs config and header script # live outside the package directory but change this site too. + # The diff is taken against the merge base (origin/main...HEAD), not + # against the tip of main: a two-dot diff also reports everything that + # landed on main after the PR branched, which made every PR that was + # behind main build every site. The checkout is shallow, so fetch the + # full history first; without a merge base the diff fails and the build + # runs, which is the safe default. - | - if [ "$READTHEDOCS_VERSION_TYPE" = "external" ] && git diff --quiet origin/main -- packages/zarr-metadata packages/mkdocs-base.yml packages/source-version.js; + if [ "$READTHEDOCS_VERSION_TYPE" = "external" ]; then - exit 183; + git fetch --quiet --unshallow origin main pull/$READTHEDOCS_VERSION_NAME/head || true; + if git diff --quiet origin/main...HEAD -- packages/zarr-metadata packages/mkdocs-base.yml packages/source-version.js; + then + exit 183; + fi fi install: - pip install --upgrade pip diff --git a/packages/zarr-metadata/pyproject.toml b/packages/zarr-metadata/pyproject.toml index 31d548bf2a..109f5b48df 100644 --- a/packages/zarr-metadata/pyproject.toml +++ b/packages/zarr-metadata/pyproject.toml @@ -56,6 +56,10 @@ docs = [ "mkdocs-material==9.7.7", "mkdocs==1.6.1", "mkdocstrings==1.0.6", + # pymdown-extensions 12.3 changed the Highlight extension API; mkdocstrings 1.0.6 + # cannot drive it (Highlight.__init__() missing argument "md"). Match the + # version in the repo-root uv.lock until mkdocstrings is bumped everywhere. + "pymdown-extensions==11.0.1", "mkdocstrings-python==2.0.8", "griffe-inherited-docstrings==1.1.3", # mkdocstrings uses ruff to format rendered signatures diff --git a/packages/zarr-metadata/uv.lock b/packages/zarr-metadata/uv.lock index 07ad9a0ebe..52967144b5 100644 --- a/packages/zarr-metadata/uv.lock +++ b/packages/zarr-metadata/uv.lock @@ -773,15 +773,15 @@ wheels = [ [[package]] name = "pymdown-extensions" -version = "12.1" +version = "11.0.1" source = { registry = "https://pypi.org/simple" } dependencies = [ { name = "markdown" }, { name = "pyyaml" }, ] -sdist = { url = "https://files.pythonhosted.org/packages/2a/94/858e0163cb4d83d6d8234018a01792c749a56daee41794cac7d6c46661e8/pymdown_extensions-12.1.tar.gz", hash = "sha256:fdb8f47f5d7fd069d10ef2a7d8908e613d7865ff0419d544a0ffd3984e884f11", size = 868245, upload-time = "2026-09-23T00:08:42Z" } +sdist = { url = "https://files.pythonhosted.org/packages/21/a9/5f0c535ba3b08fe09270c16808e053a968868242ecbd5676d4e3a488bf28/pymdown_extensions-11.0.1.tar.gz", hash = "sha256:dd2905ae6fc5b75582fafb139a1266ffc754705efa902aa50067fa7ff4f94ec0", size = 857113, upload-time = "2026-07-02T17:59:22.955Z" } wheels = [ - { url = "https://files.pythonhosted.org/packages/36/d1/98313da89960a604402266a115311b510254900ff1295ea426403f9423cc/pymdown_extensions-12.1-py3-none-any.whl", hash = "sha256:4a254b771acfcddc6c110a7f4590d818f1f849e2d5aacf69b4b07c8dd2a9700d", size = 277069, upload-time = "2026-09-23T00:08:40.069Z" }, + { url = "https://files.pythonhosted.org/packages/d6/54/da572c98c0b77626a91b5d3b89f0231d8bff5125c225420908632f8b342d/pymdown_extensions-11.0.1-py3-none-any.whl", hash = "sha256:db3943a62bab7e03af1364f0c4083e64b91fb097675a4b6cceccfbe9a77e5eb2", size = 269455, upload-time = "2026-07-02T17:59:21.271Z" }, ] [[package]] @@ -1145,6 +1145,7 @@ docs = [ { name = "mkdocs-material" }, { name = "mkdocstrings" }, { name = "mkdocstrings-python" }, + { name = "pymdown-extensions" }, { name = "ruff" }, ] test = [ @@ -1164,6 +1165,7 @@ docs = [ { name = "mkdocs-material", specifier = "==9.7.7" }, { name = "mkdocstrings", specifier = "==1.0.6" }, { name = "mkdocstrings-python", specifier = "==2.0.8" }, + { name = "pymdown-extensions", specifier = "==11.0.1" }, { name = "ruff", specifier = "==0.16.8" }, ] test = [ From 2c6f1173e5d0b542a851e4c62c6a47c2579df0dc Mon Sep 17 00:00:00 2001 From: Davis Vann Bennett Date: Wed, 21 Oct 2026 15:39:15 +0200 Subject: [PATCH 2/2] docs: add changelog entry for #4543 Assisted-by: ClaudeCode:claude-fable-5.1 Co-Authored-By: Claude Fable 5.1 --- changes/4543.misc.md | 1 + 1 file changed, 1 insertion(+) create mode 100644 changes/4543.misc.md diff --git a/changes/4543.misc.md b/changes/4543.misc.md new file mode 100644 index 0000000000..54be050e61 --- /dev/null +++ b/changes/4543.misc.md @@ -0,0 +1 @@ +Fixed the Read the Docs builds of the zarr-indexing, zarr-metadata and zarr-http-server documentation sites, which failed after an unpinned `pymdown-extensions` release, and made pull request builds of those sites skip when the pull request does not change the package.