Read the Docs 项目构建过程自定义指南

最新推荐文章于 2025-06-12 09:11:55 发布

汤萌妮Margaret

最新推荐文章于 2025-06-12 09:11:55 发布

阅读量306

点赞数 4

CC 4.0 BY-SA版权

本文链接：https://blog.youkuaiyun.com/gitblog_01121/article/details/148441194

Read the Docs 项目构建过程自定义指南

readthedocs.org The source code that powers readthedocs.org 项目地址: https://gitcode.com/gh_mirrors/re/readthedocs.org

概述

Read the Docs 是一个流行的文档托管平台，它提供了标准化的文档构建流程。然而，不同项目可能有特殊需求，因此平台提供了灵活的构建过程自定义功能。本文将详细介绍如何在 Read the Docs 项目中自定义构建过程。

构建过程自定义的两种方式

1. 扩展或覆盖标准构建流程

这种方式适合希望保留 MkDocs 或 Sphinx 默认构建命令，但需要添加额外步骤或修改部分命令的项目。

2. 完全自定义构建流程

这种方式适合需要完全控制构建过程的项目，可以使用任何能生成 HTML 的工具。

可自定义的构建阶段

Read the Docs 的构建过程分为多个阶段，每个阶段都提供了钩子让用户插入自定义命令：

| 构建阶段 | 可自定义的钩子 | |---------|---------------| | 代码检出 | post_checkout | | 系统依赖 | pre_system_dependencies, post_system_dependencies | | 创建环境 | pre_create_environment, create_environment, post_create_environment | | 安装依赖 | pre_install, install, post_install | | 构建文档 | pre_build, build, post_build | | 上传结果 | 当前不可自定义 |

注意：checkout、system_dependencies 和 upload 这些预定义作业不能被覆盖或跳过。

配置示例

以下是一个典型的 .readthedocs.yaml 配置文件示例，展示了如何自定义构建过程：

version: 2
formats: [htmlzip, pdf]
sphinx:
  configuration: docs/conf.py
python:
  install:
    - requirements: docs/requirements.txt
build:
  os: "ubuntu-22.04"
  tools:
    python: "3.10"
  jobs:
    pre_install:
      - bash ./scripts/pre_install.sh
    build:
      htmlzip:
        - echo "覆盖 htmlzip 格式的默认构建命令"
        - mkdir -p $READTHEDOCS_OUTPUT/htmlzip/
        - echo "Hello, world!" > $READTHEDOCS_OUTPUT/htmlzip/index.zip
    post_build:
      - curl -X POST \
        -F "project=${READTHEDOCS_PROJECT}" \
        -F "version=${READTHEDOCS_VERSION}" https://example.com/webhooks/readthedocs/

重要特性与限制

工作目录：命令执行时的工作目录是项目仓库的根目录
环境变量：每条命令都会展开环境变量
命令隔离：每条命令都在新的 shell 进程中执行，环境变量修改不会保留
错误处理：任何命令返回非零退出码都会导致构建立即失败
必要配置：使用 build.jobs 时必须指定 build.os 和 build.tools
默认行为：
- 如果定义了 Sphinx 或 MkDocs 配置，相关阶段会使用默认命令
- 如果未定义，相关阶段默认不执行任何操作

输出文件位置

当覆盖构建步骤时，你需要自行生成 HTML 和其他格式的文档。Read the Docs 会托管 $READTHEDOCS_OUTPUT/<format>/ 目录中的内容。

支持的格式及其对应目录：

$READTHEDOCS_OUTPUT/html/ (必需)
$READTHEDOCS_OUTPUT/htmlzip/
$READTHEDOCS_OUTPUT/pdf/
$READTHEDOCS_OUTPUT/epub/

注意：在添加内容前，请确保创建了相应的输出目录。

搜索功能支持

Read the Docs 会自动索引所有 HTML 文件的内容，并遵循配置中的搜索选项。搜索结果可以通过仪表板或搜索 API 访问。

替代语法

除了 build.jobs，还可以使用 build.commands 完全覆盖构建过程：

version: 2
build:
  os: "ubuntu-22.04"
  tools:
    python: "3.10"
  commands:
    - pip install pelican
    - pelican --settings docs/pelicanconf.py --output $READTHEDOCS_OUTPUT/html/ docs/

但我们推荐使用 build.jobs，因为它提供了更结构化的方式，支持为不同格式定义不同命令，还能通过 build.apt_packages 安装系统依赖。

实用示例

1. 完整 Git 克隆

version: 2
build:
  os: "ubuntu-20.04"
  tools:
    python: "3.10"
  jobs:
    post_checkout:
      - git fetch --unshallow || true
      - git config remote.origin.fetch '+refs/heads/*:refs/remotes/origin/*' || true
      - git fetch --all --tags || true

2. 基于条件取消构建

version: 2
build:
  os: "ubuntu-22.04"
  tools:
    python: "3.12"
  jobs:
    post_checkout:
      - |
        if [ "$READTHEDOCS_VERSION_TYPE" = "external" ] && git diff --quiet origin/main -- docs/ .readthedocs.yaml;
        then
          exit 183;
        fi

3. 使用 Doxygen 生成文档

version: 2
build:
  os: "ubuntu-20.04"
  tools:
    python: "3.10"
  jobs:
    pre_build:
      - doxygen

4. 安装 Node.js 依赖

version: 2
build:
  os: "ubuntu-22.04"
  tools:
    python: "3.9"
    nodejs: "16"
  jobs:
    post_install:
      - npm ci
      - npm install -g jsdoc

5. 使用 Poetry 安装依赖

version: 2
build:
  os: "ubuntu-22.04"
  tools:
    python: "3.10"
  jobs:
    post_install:
      - pip install poetry
      - VIRTUAL_ENV=$READTHEDOCS_VIRTUALENV_PATH poetry install --with docs
sphinx:
  configuration: docs/conf.py

6. 检查损坏的链接

version: 2
build:
  os: "ubuntu-20.04"
  tools:
    python: "3.10"
  jobs:
    pre_build:
      - python -m sphinx -b linkcheck -D linkcheck_timeout=1 docs/ $READTHEDOCS_OUTPUT/linkcheck