在Read the Docs中使用uv加速Python文档构建

Read the Docs作为流行的文档托管平台，其构建速度直接影响开发者的工作效率。本文将介绍如何利用uv这一新兴的Python包管理工具来显著提升文档构建速度。

uv的优势

uv是由Astral团队开发的Python包管理工具，相比传统pip具有以下优势：

• 极快的依赖解析速度
• 高效的缓存机制
• 兼容现有pip工作流
• 支持现代Python包管理特性

实测表明，使用uv可以将构建时间从115秒缩短至69秒，节省40%以上的时间。

基本配置方法

在.readthedocs.yml文件中，可以通过以下配置启用uv：

version: 2
build:
  os: ubuntu-24.04
  tools:
    python: "3.13"
  jobs:
    pre_create_environment:
      - asdf plugin add uv
      - asdf install uv latest
      - asdf global uv latest
    create_environment:
      - uv venv
    install:
      - uv pip install -r requirements.txt
    build:
      html:
        - uv run sphinx-build -T -b html docs $READTHEDOCS_OUTPUT/html

高级优化技巧

1. 缓存优化：通过设置缓存目录可以进一步提升速度

   install:
     - uv pip install --cache-dir $READTHEDOCS_VIRTUALENV_PATH/../../uv_cache -r requirements.txt
   

2. 依赖组支持：使用uv sync替代uv pip可以支持PEP 735依赖组

   install:
     - uv sync pyproject.toml --system
   

3. 环境变量配置：确保正确设置VIRTUAL_ENV变量

   install:
     - VIRTUAL_ENV=$READTHEDOCS_VIRTUALENV_PATH uv pip install -r docs/requirements.txt
   

与传统方法的对比

传统pip构建流程通常包含以下耗时步骤：

• 升级pip和setuptools（约18秒）
• 安装Sphinx扩展（约20秒）
• 安装项目依赖（时间随项目复杂度变化）

使用uv后：

• 依赖解析几乎瞬时完成
• 安装步骤大幅缩短
• 整体构建时间可减少50%以上

注意事项

1. 目前必须通过build.jobs配置使用uv，python.install.method暂不支持uv选项

2. 对于简单项目，权衡uv安装时间（约4秒）与节省的时间

3. 建议在CI中预生成requirements.lock文件，进一步加速构建

通过合理配置uv，开发者可以显著提升Read the Docs的文档构建效率，特别是在大型项目或频繁更新的场景下效果更为明显。