From 408a4fc0e737e4ee3702f38d4199db394724a6ee Mon Sep 17 00:00:00 2001 From: thodson-usgs Date: Sat, 15 Aug 2026 11:35:09 -0500 Subject: [PATCH] ci(docs): fail the docs job when its install fails Setting `shell:` replaces the default `bash -e {0}`, and `bash -l {0}` carries no `-e`, so a failed `pip install .[doc,nldi]` did not stop the step. The build ran on against whatever was already on the runner and died later at `sphinx-build: not found` (exit 127), naming the wrong culprit. Worse, the step exits 0 whenever a stale sphinx is present, so docs built from a failed install would deploy to gh-pages as if nothing were wrong. Also stop building on tag pushes. Naming `branches` alone is what excludes them -- "if you define only branches/branches-ignore, the workflow won't run for events affecting the undefined Git ref" -- while `tags-ignore` alone would have excluded branches instead and stopped docs entirely. The deploy step is gated on refs/heads/main, so a tag build can never publish; GitHub pushes an `untagged-` placeholder tag for every draft release, and each one started a docs build that failed in setuptools_scm, which cannot parse that ref as a version. Both were surfaced by the v1.3.0 release going out with `untagged-13b6562c80438aa8ea78` as its tag instead of `v1.3.0`. Co-Authored-By: Claude Fable 5 --- .github/workflows/sphinx-docs.yml | 13 ++++++++++++- 1 file changed, 12 insertions(+), 1 deletion(-) diff --git a/.github/workflows/sphinx-docs.yml b/.github/workflows/sphinx-docs.yml index 7d75ac181..8521f8736 100644 --- a/.github/workflows/sphinx-docs.yml +++ b/.github/workflows/sphinx-docs.yml @@ -3,7 +3,15 @@ name: Sphinx Docs Build on: + # Every branch, no tags. Naming ``branches`` alone is what excludes tags: + # "if you define only branches/branches-ignore, the workflow won't run for + # events affecting the undefined Git ref". A tag push builds docs that can + # never deploy -- the deploy step is gated on ``refs/heads/main`` -- and + # GitHub pushes an ``untagged-`` placeholder tag for every draft + # release, so tag runs are a red X for work no one asked for. push: + branches: + - "**" pull_request: # Serialize runs for the same ref so two near-simultaneous pushes to main @@ -37,7 +45,10 @@ jobs: python-version: "3.13" cache: "pip" - name: Install dataretrieval, dependencies, and Sphinx then build docs - shell: bash -l {0} + # ``-e`` is not the default once ``shell:`` is overridden, and without it + # a failed ``pip install`` here does not stop the step: the build runs on + # from a stale or absent install, and a docs set built that way deploys. + shell: bash -leo pipefail {0} run: | python -m pip install --upgrade pip pip install .[doc,nldi]