Make failures actionable and harden validation, APIs, and CI #1332
Workflow file for this run
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| # This workflow builds the sphinx docs | |
| name: Sphinx Docs Build | |
| on: | |
| push: | |
| pull_request: | |
| # Serialize runs for the same ref so two near-simultaneous pushes to main | |
| # don't race to force-push gh-pages. Without this, the second deploy fails | |
| # with "cannot lock ref 'refs/heads/gh-pages'" because the first run advanced | |
| # the branch after the second had already read its tip. Queue rather than | |
| # cancel (cancel-in-progress: false) so every commit's docs still deploy. | |
| concurrency: | |
| group: ${{ github.workflow }}-${{ github.ref }} | |
| cancel-in-progress: false | |
| 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 | |
| with: | |
| persist-credentials: false | |
| - name: Set up Python | |
| uses: actions/setup-python@v6 | |
| with: | |
| python-version: "3.13" | |
| cache: "pip" | |
| - name: Install dataretrieval, dependencies, and Sphinx then build docs | |
| shell: bash -l {0} | |
| run: | | |
| python -m pip install --upgrade pip | |
| pip install .[doc,nldi] | |
| ipython kernel install --name "python3" --user | |
| # 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: | | |
| echo $REF | |
| echo $EVENT_NAME | |
| echo ${{ github.event_name == 'push' }} | |
| echo ${{ github.ref == 'refs/heads/main' }} | |
| echo ${{ github.event_name == 'push' && github.ref == 'refs/heads/main' }} | |
| - name: Deploy to GitHub Pages | |
| uses: JamesIves/github-pages-deploy-action@v4 | |
| if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/main' }} | |
| with: | |
| GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} | |
| EVENT_NAME: ${{ github.event_name }} | |
| REF: ${{ github.ref }} | |
| BRANCH: gh-pages | |
| FOLDER: docs/build/html |