uv in ReadTheDocs

[cthoyt]

This is more of a "show and tell" than an issue, but it could be something worth incorporating into the uv documentation.

Using uv as the installer instead of pip

ReadTheDocs uses pip by default when installing sphinx, your package, and its dependencies. The build can be greatly sped up by switching to uv, but this isn't easy to configure without making a custom override in the commands. Here's an example readthedocs.yml that makes it work using uv pip install as an alternative, that uses the asdf program for configuring uv:

# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
version: 2

build:
  os: ubuntu-22.04
  tools:
    python: "3.12"

  # adapted from uv recipe at https://docs.readthedocs.io/en/stable/build-customization.html#install-dependencies-with-uv
  # and comment at https://github.com/readthedocs/readthedocs.org/issues/11289#issuecomment-2103832834
  commands:
    - asdf plugin add uv
    - asdf install uv latest
    - asdf global uv latest
    - uv venv $READTHEDOCS_VIRTUALENV_PATH
    - VIRTUAL_ENV=$READTHEDOCS_VIRTUALENV_PATH uv --preview pip install .[docs,pandas,flask,fastapi,rdflib]
    - python -m sphinx -T -b html -d docs/_build/doctrees -D language=en docs/source $READTHEDOCS_OUTPUT/html

Note: this example is adapted from https://github.com/cthoyt/curies where the docs extra installs sphinx, sphinx-click, sphinx-rtd-theme, and other related documentation build dependencies.

Here's an example build log from the website for this project: https://app.readthedocs.org/projects/curies/builds/26642806/

Getting uv's build backend to work while it's in preview

If you've already switched your package to using uv's preview build backend, then you have to make sure to pass either --preview when calling uv, or setting UV_PREVIEW=1 in the command line. In the above scenario, where you have control over the commands that are being run, then this is pretty straightforward.

Something I am still working on: if you want to keep using the default installer (pip) because you don't want to configure too much here, but have a package that's using the uv build backend. If you try and pip install a package with the uv build backend without setting UV_PREVIEW=1 in the environment, the build will fail. I wasn't yet able to figure out how to use another part of ReadTheDocs' build process customization to set this environment variable in a way that worked. If anyone has a clean idea on this, then it would be great to comment here!