Switch recommended build workflow from conda to uv

[jacobtomlinson]

Our current recommended workflow for building these docs is to create a conda environment and build within it. One challenge we face with this is sometimes the upstream Sphinx theme changes things and breaks the layout. For most developers the local conda build environment only gets updates occasionally, so these breakages may not be immediately reproducible locally without clearing and recreating the environment.

We can solve this with uv and having a uv.lock file which ensures reproducible builds consistently. The only requirement is to have uv installed on your system and to prefix build commands with uv run. The Python environment will be created dynamically using the uv.lock. We can upgrade the lockfile by deleting it and running things again, the dependencies will be calculated from the specification in pyproject.toml.

This also means that is a PR modifies some dependencies or versions we don't need to worry about the local environment being in sync, just check out the PR and uv run will update the environment to match the new uv.lock automatically. Switch back to main and the environment is put back again.

Interactive development builds become:

# Install uv if you don't have it already
# curl -LsSf https://astral.sh/uv/install.sh | sh

# Run sphinx-autobuild
uv run sphinx-autobuild source build/html

Builds are also faster. Not a huge impact given that they are pretty quick already, but a conda based build takes around 1m9s and a uv build takes 29s.

[jacobtomlinson]

Linting failures should be fixed by #558

[review-notebook-app]

Check out this pull request on 

See visual diffs & provide feedback on Jupyter Notebooks.

---

Powered by ReviewNB

[ncclementi]

Thanks for adding this, it makes sense.

I left one comment, I think it would be good to add a line on when and how we need to recreate the uv.lock file

[ncclementi]

LGTM 🚀