From 68be9adc86e2b1fadd501cb7644386b9d62e9f58 Mon Sep 17 00:00:00 2001 From: thodson-usgs Date: Fri, 7 Aug 2026 13:09:22 -0500 Subject: [PATCH] ci(docs): stop installing an unused TeX stack; bound the job The docs build on main ran 150 minutes instead of its usual 6. Nothing in the build got slower: the commit it ran on (#356) touched only CI config, and timing the two runs against each other shows notebook execution took 3.7 min in both. The whole 144 min difference was `apt` fetching the same 127 packages -- 314 MB at an effective 37 KB/s off a slow Azure mirror. Most of that download is a TeX stack an HTML build never reaches. No math extension is configured and nothing renders math to images, so latexmk, texlive-*, and dvipng -- ~266 MB, and 5 of the 6 slowest single-package waits in the bad run -- were downloaded and never executed. Dropping them removes the tail risk rather than reducing it: with pandoc alone (which nbsphinx does shell out to, and without which the build fails) there is no longer a large download to be slow. Verified by building with the TeX binaries off PATH: it succeeds, and all 44 non-notebook HTML pages are byte-identical to a build with them present. A bound belongs here regardless, since the next slow mirror will find whatever is left. `timeout-minutes: 30` is far under the 6 h default and well over a healthy build. It matters more than it looks: runs are serialized on the ref, so an unbounded run doesn't just lose its own docs, it holds the queue for every commit behind it -- which is why this surfaced as "docs are stuck on main" rather than as one slow run. Co-Authored-By: Claude Opus 5 --- .github/workflows/sphinx-docs.yml | 19 ++++++++++++++++++- 1 file changed, 18 insertions(+), 1 deletion(-) diff --git a/.github/workflows/sphinx-docs.yml b/.github/workflows/sphinx-docs.yml index 2640e6b6..7d75ac18 100644 --- a/.github/workflows/sphinx-docs.yml +++ b/.github/workflows/sphinx-docs.yml @@ -18,6 +18,14 @@ concurrency: jobs: docs: runs-on: ubuntu-latest + # A normal build is ~6 min, nearly all of it executing the example + # notebooks against live USGS services. The cap is well above that but far + # below the 6 h default, so a build that stops making progress -- a slow apt + # mirror, a service that never answers -- fails while the queue behind it is + # still short. Serialized runs (see ``concurrency`` above) queue rather than + # cancel, so an unbounded run blocks every later commit's docs, not just its + # own. + timeout-minutes: 30 steps: - name: Checkout uses: actions/checkout@v6 @@ -34,7 +42,16 @@ jobs: python -m pip install --upgrade pip pip install .[doc,nldi] ipython kernel install --name "python3" --user - sudo apt update -y && sudo apt install -y latexmk texlive-latex-recommended texlive-latex-extra texlive-fonts-recommended dvipng pandoc + # pandoc only: nbsphinx shells out to it to convert notebook markdown + # cells, so the build fails without it. The TeX stack this used to + # install alongside it (latexmk, texlive-*, dvipng -- ~266 MB) is not + # reachable from an HTML build: no math extension is configured and + # nothing renders math to images, so it was downloaded and never run. + # It was also the whole tail risk -- 127 packages off one apt mirror, + # which on a bad day delivered 314 MB at 37 KB/s and turned a 6 min + # build into 150 min. Restore it only alongside a builder that needs + # it (``latexpdf``), not for HTML. + sudo apt update -y && sudo apt install -y pandoc (cd docs && make html) - name: Debug run: |