ci: pass API_USGS_PAT to docs + tests; cache Sphinx build outputs

[thodson-usgs]

Two small CI improvements that compound. Targeted at the doc-build and live-test workflows that hit the live Water Data API.

Commits

ci: pass API_USGS_PAT to docs + test workflows when the secret is set	Adds env: API_USGS_PAT: ${{ secrets.API_USGS_PAT }} to the build step in sphinx-docs.yml and the pytest step in python-package.yml.
ci(docs): cache Sphinx build outputs across runs	Adds actions/cache@v4 on docs/build/ keyed on source hashes, so unchanged notebooks aren't re-executed on the next CI run.

What problem this solves

1. The doc build runs every notebook live on every CI invocation. The project convention is no committed notebook outputs (verified on main — all .ipynb ship with empty outputs arrays), so nbsphinx's default 'auto' mode executes every notebook against the live API on every push and pull_request.
2. Currently unauthenticated. No workflow references API_USGS_PAT today, so the doc build (and the live tests in python-package.yml) hit the ~60 req/min unauthenticated rate limit. As the demo notebook set grows this becomes increasingly fragile.

What this PR does

Commit 1 — pass through API_USGS_PAT

The change is purely additive: if secrets.API_USGS_PAT is configured (in repo settings), both workflows pick up the authenticated quota. If it isn't, the env var resolves to an empty string and the workflows fall back to today's unauthenticated behavior — no observable change until the secret is added.

Maintainer action required: add API_USGS_PAT as an Actions secret in repo settings to actually pick up the higher rate limit. The PR is no-op until then.

Commit 2 — cache Sphinx build outputs

actions/cache@v4 persists docs/build/ (which includes .doctrees/) across CI runs. Sphinx checks source mtimes against the doctree; unchanged sources skip re-parsing, which for nbsphinx (nbsphinx_execute='auto') means unchanged notebooks aren't re-executed. The cache key hashes every input that affects the rendered docs — notebooks, RST/MD, conf.py, and the Python package (autodoc reads docstrings) — so any source change invalidates exact-match. The restore-keys: sphinx- fallback gives partial-match recovery: even a key miss restores recent doctrees, and Sphinx then only re-builds the files whose source actually changed.

Result: most PRs only touch a handful of files, so the doc build re-executes only the actually-changed notebooks instead of the whole 19-notebook set.

What this PR does NOT do (intentional)

• Doesn't switch to MyST-NB + jupyter-cache. That's the canonical "adopt jupyter-cache" path (nb_execution_mode = 'cache' integrates jupyter-cache natively), but it requires reworking the existing .nblink references to external notebooks under demos/. Caching docs/build/ via actions/cache achieves the equivalent functional benefit without the doc-tree rewrite. The MyST-NB migration is a worthwhile larger follow-up.
• Doesn't add the API_USGS_PAT secret (can't be done from code; that's a repo-settings action).
• Doesn't change any notebook or doc content.

🤖 Generated with Claude Code