More concise uv example

[lengau]

This provides a more succinct uv example using uv sync. It also has the benefit of not requiring overriding of any build steps.

---

📚 Documentation previews 📚

• User's documentation (docs): https://docs--11946.org.readthedocs.build/en/11946/

• Developer's documentation (dev): https://dev--11946.org.readthedocs.build/en/11946/

[ericholscher]

Seems this is removing the build step completely?

[lengau]

It's no longer overriding the build step because it doesn't need to, since uv is installing things in the regular RTD virtualenv. Here's a screenshot of a real run of this (from canonical/starbase#330):

[lengau]

And the full build log: starbase-build-log.txt

[lengau]

And another example: https://github.com/canonical/craft-application/blob/main/.readthedocs.yaml

Build log

Output

[ericholscher]

This example still isn't really a common uv use case though? I think we want to show people how to use uv in a way that makes it really clear what the steps are?

[lengau]

I'm not sure why this wouldn't be a common uv case? This is using uv's project management and lock file, where the previous example uses uv as a drop-in replacement for pip but doesn't use uv.lock This also matches quite well to the poetry steps above the example.

[coroa]

Fully agree with @lengau here. While the uv example currently in the docs, relies on requirements.txt superseeded by dependencies and dependency-groups in pyproject.toml and breaks all output formats except for html, this one is able to just really on the default build steps making it a lot more flexible.

I did propose essentially the same strategy in #12033, only moving the package installation fully into create_environment. As in #12033, i would only add the --add-extras flag to uv sync.

[ericholscher]

The problem with this update is that it doesn't explain uv sync. It presumably is depending on other files/state somewhere, which should be noted.

[coroa]

The problem with this update is that it doesn't explain uv sync. It presumably is depending on other files/state somewhere, which should be noted.

Hmm, uv sync is implicit in uv run, so the current setup is pulling in the same state, which is pyproject.toml and uv.lock (if the latter exists).

All of that is explained in good detail in the uv projects guide .

The lesser known trick here is that setting the environment variable UV_PROJECT_ENVIRONMENT="${READTHEDOCS_VIRTUALENV_PATH}" makes uv update the environment where the default readthedocs build steps expect it, so that it integrates seamlessly. That is the exact same strategy used for poetry as described at https://docs.readthedocs.com/platform/stable/build-customization.html#id14 .

But anyway, I hear that by adding a bit of context around this update, you think it would become acceptable. I'll propose something then.

[ericholscher]

But anyway, I hear that by adding a bit of context around this update, you think it would become acceptable. I'll propose something then.

Yea, I think explaining the code snippet and what state is required to make it work is great. We have requirements and other things mentioned a lot in our docs, but don't have uv specific stuff anywhere. It can definitely be a link out to the uv docs tho, but at least something.

[lengau]

Superseded by #12064