如何配置.readthedocs.yaml让ReadTheDocs使用Graphviz构建图表？

问题根源 #

你之前的两种配置都存在误区：

• 第一种使用sudo，但Read the Docs的构建容器默认无sudo权限，因此报错找不到sudo命令
• 第二种直接执行apt-get，但普通用户没有系统包安装权限，导致无法锁定依赖目录

正确配置方法 #

Read the Docs提供了专门的apt_packages配置字段用于安装系统级依赖，无需手动编写apt命令。直接在.readthedocs.yaml中添加该字段即可：

build:
  os: ubuntu-22.04
  tools:
    python: "3.11"

# 配置需要安装的系统依赖包
apt_packages:
  - graphviz

# 若有Python依赖，可在此配置（可选）
python:
  install:
    - requirements: docs/requirements.txt

说明 #

• apt_packages字段会让Read the Docs在构建前自动以合适权限安装指定系统包，无需手动执行apt-get update或apt-get install
• 配置完成后，Sphinx的sphinx.ext.autodoc扩展即可找到dot命令，生成图表时不会再出现警告

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