More concise uv example with docs (#12064)

As a follow up to #11946 (updating the uv example to rely on uv's
project management capabilities) , I added here a few paragraphs on what
the new `uv` example achieves.

I hope that makes it acceptable for integration @ericholscher .

@lengau , it would be appreciated if you could review, that this matches
your expectation as well.

Thank you

<!-- readthedocs-preview docs start -->
---
:books: Documentation previews :books:

- User's documentation (`docs`):
https://docs--12064.org.readthedocs.build/12064/

<!-- readthedocs-preview docs end -->

<!-- readthedocs-preview dev start -->
- Developer's documentation (`dev`):
https://dev--12064.org.readthedocs.build/12064/

<!-- readthedocs-preview dev end -->

---------

Co-authored-by: Alex Lowe <[email protected]>
Co-authored-by: Eric Holscher <[email protected]>
Co-authored-by: Manuel Kaufmann <[email protected]>
Co-authored-by: Eric Holscher <[email protected]>

Author: 4 people

docs/user/build-customization.rst

@@ -450,33 +450,41 @@ Take a look at the following example:
 Install dependencies with ``uv``
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Projects can use `uv <https://github.com/astral-sh/uv/>`__,
-to install Python dependencies, usually reducing the time taken to install compared to pip.
-Take a look at the following example:
+Projects managed with `uv <https://github.com/astral-sh/uv/>`__ can install `uv` with asdf,
+and then rely on it to set up the environment and install the python project and its dependencies.
+Read the Docs' own build steps expect it by setting the ``UV_PROJECT_ENVIRONMENT`` variable,
+usually reducing the time taken to install compared to pip.
+
+The following examples assumes a uv project as described in its
+`projects concept <https://docs.astral.sh/uv/concepts/projects/>`__. As an introduction
+refer to its `Working on projects guide <https://docs.astral.sh/uv/guides/projects/>`__.
+The ``docs`` dependency group which should is pulled in during the ``uv sync`` step (if additional
+extras are required they can be added with the `--extra attribute <https://docs.astral.sh/uv/concepts/projects/sync/#syncing-optional-dependencies>`__).
 
+If a ``uv.lock`` file exists it is respected.
 
 .. code-block:: yaml
+
    :caption: .readthedocs.yaml
 
    version: 2
 
+   sphinx:
+      configuration: docs/conf.py
+
    build:
       os: ubuntu-24.04
       tools:
          python: "3.13"
       jobs:
-         create_environment:
+         pre_create_environment:
             - asdf plugin add uv
             - asdf install uv latest
             - asdf global uv latest
-            - uv venv
+         create_environment:
+            - uv venv "${READTHEDOCS_VIRTUALENV_PATH}"
          install:
-            - uv pip install -r requirements.txt
-         build:
-            html:
-               - uv run sphinx-build -T -b html docs $READTHEDOCS_OUTPUT/html
-
-MkDocs projects could use ``NO_COLOR=1 uv run mkdocs build --strict --site-dir $READTHEDOCS_OUTPUT/html`` instead.
+            - UV_PROJECT_ENVIRONMENT="${READTHEDOCS_VIRTUALENV_PATH}" uv sync --frozen --group docs
 
 Update Conda version
 ~~~~~~~~~~~~~~~~~~~~