如何将GitHub Actions的Wheel包用于加速ReadTheDocs构建？

步骤1：在GitHub Actions中生成并上传Wheel到GitHub Releases #

在你的GitHub Actions workflow文件（比如.github/workflows/build-wheel.yml）里，补充上传Wheel到GitHub Releases的步骤，确保文档构建版本能匹配到对应预编译包：

jobs:
  build-wheel:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      # 保留你现有生成Wheel的步骤，比如用maturin构建
      - name: Build Wheel
        run: maturin build --release --out dist
      # 将Wheel上传到对应版本的GitHub Release
      - name: Upload Wheel to Release
        uses: actions/upload-release-asset@v1
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        with:
          upload_url: ${{ github.event.release.upload_url }}
          asset_path: ./dist/*.whl
          asset_name: ${{ github.event.repository.name }}-${{ github.ref_name }}-manylinux_2_17_x86_64.whl
          asset_content_type: application/octet-stream

注：如果需要分支构建的文档加速，可以调整workflow触发条件（比如push到主分支时触发），并将Wheel上传到GitHub Artifacts；多平台支持则需要在不同系统的runner上分别构建上传。

步骤2：修改ReadTheDocs配置文件（.readthedocs.yaml） #

更新配置跳过Rust编译流程，直接安装预构建Wheel：

version: 2

build:
  os: ubuntu-22.04
  tools:
    python: "3.10"
  # 移除所有Rust相关的环境配置，不需要再编译
  apt_packages: []

python:
  install:
    # 直接从GitHub Release拉取对应版本的Wheel安装
    - method: pip
      path: "https://github.com/你的用户名/你的仓库/releases/download/${{ env.READTHEDOCS_VERSION_NAME }}/你的包名-${{ env.READTHEDOCS_VERSION_NAME }}-manylinux_2_17_x86_64.whl"
    # 安装文档构建依赖（比如sphinx等）
    - requirements: docs/requirements.txt

关键说明：

• ${{ env.READTHEDOCS_VERSION_NAME }}是RTD内置变量，自动匹配当前构建的版本（tag/分支名），保证Wheel版本和文档版本一致
• 替换URL里的用户名、仓库名、包名，必须和上传的Wheel文件名完全匹配

步骤3：确保本地文档构建不受影响 #

本地执行常规文档构建命令（比如sphinx-build docs docs/_build/html）即可，本地环境会自动编译Rust库（未安装时）或使用已安装的包，完全不受RTD配置的约束，不会出现CI绑定的问题。

额外优化建议 #

• 针对不同Python版本生成对应Wheel，在RTD配置中根据环境选择匹配的包
• 若不想用GitHub Releases，可将Wheel上传到PyPI测试版，在RTD中安装测试版包
• 可在RTD配置中启用依赖缓存，减少重复下载Wheel的耗时

内容的提问来源于stack exchange，提问作者Ianhi