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

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

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

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

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