ci(docs): fix the Read the Docs sub-site builds and skip filters (#4543)

* 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 <noreply@anthropic.com>

* docs: add changelog entry for #4543

Assisted-by: ClaudeCode:claude-fable-5.1

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

---------

Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>

Author: d-v-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

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.

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

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

packages/zarr-http-server/uv.lock

@@ -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

packages/zarr-indexing/.readthedocs.yaml

@@ -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

packages/zarr-indexing/pyproject.toml

@@ -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

packages/zarr-indexing/uv.lock

@@ -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