From 40631ea437e45389f00194f1b003918c0ae5054b Mon Sep 17 00:00:00 2001 From: Zachary Ware Date: Tue, 5 May 2026 14:50:14 -0500 Subject: [PATCH 1/7] Rewrite RTD configuration to use build.jobs rather than build.commands --- .readthedocs.yml | 64 +++++++++++++++++++++++++++++++++--------------- 1 file changed, 44 insertions(+), 20 deletions(-) diff --git a/.readthedocs.yml b/.readthedocs.yml index 0a2c3f8345367f..c68da97aa59ca0 100644 --- a/.readthedocs.yml +++ b/.readthedocs.yml @@ -12,23 +12,47 @@ build: tools: python: "3" - commands: - # https://docs.readthedocs.io/en/stable/build-customization.html#cancel-build-based-on-a-condition - # - # Cancel building pull requests when there aren't changes in the Doc directory. - # - # If there are no changes (git diff exits with 0) we force the command to return with 183. - # This is a special exit code on Read the Docs that will cancel the build immediately. - - | - if [ "$READTHEDOCS_VERSION_TYPE" = "external" ] && [ "$(git diff --quiet origin/main -- Doc/ .readthedocs.yml; echo $?)" -eq 0 ]; - then - echo "No changes to Doc/ - exiting the build."; - exit 183; - fi - - - asdf plugin add uv - - asdf install uv latest - - asdf global uv latest - - make -C Doc venv html - - mkdir _readthedocs - - mv Doc/build/html _readthedocs/html + jobs: + post_checkout: + # https://docs.readthedocs.com/platform/stable/guides/build/skip-build.html#skip-builds-based-on-conditions + # + # Cancel building pull requests when there aren't changes in the Doc + # directory or RTD configuration, or if we can't cleanly merge the base + # branch. + - | + set -eux; + if [ "$READTHEDOCS_VERSION_TYPE" = "external" ]; + then + base_branch=main; + git fetch --depth=50 origin $base_branch; + for attempt in $(seq 10); + do + if ! git merge-base HEAD origin/$base_branch; + then + git fetch --deepen=50 origin $base_branch; + else + break; + fi; + done; + if ! git -c "user.name=rtd" -c "user.email=no-reply@readthedocs.org" merge --no-edit origin/$base_branch; + then + echo "Unsuccessful merge with '$base_branch' branch, skipping the build"; + exit 183; + fi; + if git diff --exit-code --stat origin/$base_branch -- Doc/ .readthedocs.yml; + then + echo "No changes to Doc/ - skipping the build."; + exit 183; + fi; + fi; + create_environment: + - echo "Skipping default environment creation" + install: + - asdf plugin add uv + - asdf install uv latest + - asdf global uv latest + build: + html: + - make -C Doc venv html + - mkdir -p "$READTHEDOCS_OUTPUT" + - mv Doc/build/html "$READTHEDOCS_OUTPUT/" From cd239555a7da9cf8f253ec27709fcebafcc8e6f8 Mon Sep 17 00:00:00 2001 From: Zachary Ware Date: Tue, 5 May 2026 15:45:25 -0500 Subject: [PATCH 2/7] fixup! Rewrite RTD configuration to use build.jobs rather than build.commands --no-stat on merge --- .readthedocs.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.readthedocs.yml b/.readthedocs.yml index c68da97aa59ca0..3fa070b6f54506 100644 --- a/.readthedocs.yml +++ b/.readthedocs.yml @@ -34,7 +34,7 @@ build: break; fi; done; - if ! git -c "user.name=rtd" -c "user.email=no-reply@readthedocs.org" merge --no-edit origin/$base_branch; + if ! git -c "user.name=rtd" -c "user.email=no-reply@readthedocs.org" merge --no-stat --no-edit origin/$base_branch; then echo "Unsuccessful merge with '$base_branch' branch, skipping the build"; exit 183; From d8a4832f622cee1714b79405a1423fc998a6d6e4 Mon Sep 17 00:00:00 2001 From: Zachary Ware Date: Tue, 5 May 2026 15:47:49 -0500 Subject: [PATCH 3/7] Use stricter Bash options MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: 🇺🇦 Sviatoslav Sydorenko (Святослав Сидоренко) --- .readthedocs.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.readthedocs.yml b/.readthedocs.yml index 3fa070b6f54506..a65f15b37dcfe3 100644 --- a/.readthedocs.yml +++ b/.readthedocs.yml @@ -20,7 +20,7 @@ build: # directory or RTD configuration, or if we can't cleanly merge the base # branch. - | - set -eux; + set -eEuxo pipefail; if [ "$READTHEDOCS_VERSION_TYPE" = "external" ]; then base_branch=main; From e4aa5df07e2844162664aa71c01d42cb50004f3a Mon Sep 17 00:00:00 2001 From: Zachary Ware Date: Tue, 5 May 2026 15:50:35 -0500 Subject: [PATCH 4/7] sh not Bash MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: 🇺🇦 Sviatoslav Sydorenko (Святослав Сидоренко) --- .readthedocs.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.readthedocs.yml b/.readthedocs.yml index a65f15b37dcfe3..f012b4c9d0fa98 100644 --- a/.readthedocs.yml +++ b/.readthedocs.yml @@ -20,7 +20,7 @@ build: # directory or RTD configuration, or if we can't cleanly merge the base # branch. - | - set -eEuxo pipefail; + set -eEux; if [ "$READTHEDOCS_VERSION_TYPE" = "external" ]; then base_branch=main; From c9428cc184a8a0a1c28323a700b4e0398afe8852 Mon Sep 17 00:00:00 2001 From: Zachary Ware Date: Wed, 6 May 2026 08:59:47 -0500 Subject: [PATCH 5/7] fixup! Rewrite RTD configuration to use build.jobs rather than build.commands Add explicit local branch name needed in backports --- .readthedocs.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.readthedocs.yml b/.readthedocs.yml index f012b4c9d0fa98..bdc9c0c7a2be11 100644 --- a/.readthedocs.yml +++ b/.readthedocs.yml @@ -24,7 +24,7 @@ build: if [ "$READTHEDOCS_VERSION_TYPE" = "external" ]; then base_branch=main; - git fetch --depth=50 origin $base_branch; + git fetch --depth=50 origin $base_branch:origin/$base_branch; for attempt in $(seq 10); do if ! git merge-base HEAD origin/$base_branch; From 1691254f55bdae67c3d113bac80f863eb053e714 Mon Sep 17 00:00:00 2001 From: Zachary Ware Date: Wed, 6 May 2026 09:05:55 -0500 Subject: [PATCH 6/7] fixup! Rewrite RTD configuration to use build.jobs rather than build.commands Avoid "refname 'origin/main' is ambiguous" warnings --- .readthedocs.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.readthedocs.yml b/.readthedocs.yml index bdc9c0c7a2be11..771580d36774d3 100644 --- a/.readthedocs.yml +++ b/.readthedocs.yml @@ -24,10 +24,10 @@ build: if [ "$READTHEDOCS_VERSION_TYPE" = "external" ]; then base_branch=main; - git fetch --depth=50 origin $base_branch:origin/$base_branch; + git fetch --depth=50 origin $base_branch:origin-$base_branch; for attempt in $(seq 10); do - if ! git merge-base HEAD origin/$base_branch; + if ! git merge-base HEAD origin-$base_branch; then git fetch --deepen=50 origin $base_branch; else From 569bf424be9c3d93884a8d550e89140994259466 Mon Sep 17 00:00:00 2001 From: Zachary Ware Date: Wed, 6 May 2026 09:12:46 -0500 Subject: [PATCH 7/7] fixup! Rewrite RTD configuration to use build.jobs rather than build.commands Missed these... --- .readthedocs.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.readthedocs.yml b/.readthedocs.yml index 771580d36774d3..3b8a30c0251873 100644 --- a/.readthedocs.yml +++ b/.readthedocs.yml @@ -34,12 +34,12 @@ build: break; fi; done; - if ! git -c "user.name=rtd" -c "user.email=no-reply@readthedocs.org" merge --no-stat --no-edit origin/$base_branch; + if ! git -c "user.name=rtd" -c "user.email=no-reply@readthedocs.org" merge --no-stat --no-edit origin-$base_branch; then echo "Unsuccessful merge with '$base_branch' branch, skipping the build"; exit 183; fi; - if git diff --exit-code --stat origin/$base_branch -- Doc/ .readthedocs.yml; + if git diff --exit-code --stat origin-$base_branch -- Doc/ .readthedocs.yml; then echo "No changes to Doc/ - skipping the build."; exit 183;