docs: the Getting Started page runs when the docs are built

[jmineau]

The Getting Started page now runs when the docs are built, so it shows what the code prints and the maps it draws: the particles, the footprint, and the same receptor run as a project. Part of #116.

It runs a real simulation on the HRRR files the tests already cache (14 and 15 January 2021, cropped around Salt Lake), in a temporary folder. A docs build takes about 95 s instead of 60 s on a compute node (the run is 17 s for trajectories, 2.5 s for the footprint, and 17 s again for the project). The steps are .. ipython:: python blocks from python-template v1.2.0; a block that raises or warns fails the build. The code a reader copies is what the page shows. The setup it needs (where the met is, a temporary working folder) is a hidden block.

Running it corrected the text. The page said the map shows the footprint "summed over all 24 hours", and that you should see "the most influence near the receptor". With this met crop, every particle leaves the met region after about 12 hours and its run stops there, so the footprint has about 12 hourly maps; and the map shows the footprint stretching away from the receptor, not peaking at it. The page now says that, and prints how many hours the particles went (the number changes from build to build, because the default krand: 4 draws a different seed for each run, so the prose has none). foot.sum("time") printed a screen of zeros; it now prints the shape. The page also says why the project's footprint differs a little from the one before it.

The receptor moved from 15 July 2023 18:00 UTC to 15 January 2021 08:00 UTC, inside the cached met. The output layout and the command-line example use the same time.

Workflow. docs.yml restores the tests' HRRR cache (same key met-hrrr-2021-v1), fetches it on a miss the way tests.yml does, and saves it, so a docs run on main, a pull request, or a tag finds it. zizmor passes. Building the docs locally now needs those files: STILT_TEST_MET_DIR points at them, and AGENTS.md has the one command that fetches them.

Legend fix, in its own commit. sim.plot.map() drew a legend with loc="best", which matplotlib warns about when the search takes over a second, as it does with a simulation's particles on the map. That warning fails the build, and it is a nuisance for anyone plotting a simulation. Both legends now sit in the upper right corner. The new test fails on the old code: it checks that drawing the legend never searches for a position, because the warning depends on how fast the machine is.

tests/test_docs_examples.py compiles the docs' code-block examples, so its count drops by 7: the blocks that now run in the build.

just quality-check (1,301 tests, the import contracts, 99% docstrings) and a clean just build-docs pass, as do all the pre-commit hooks.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ All tests successful. No failed tests found.

Files with missing lines	Coverage Δ
src/stilt/visualization.py	94.79% <100.00%> (ø)