如何配置sphinx-build在遇到不可读下载文件时强制构建失败

解决方案 #

首先明确-W参数不生效的原因：download file not readable属于Sphinx默认的INFO级日志，并不属于警告范畴，因此-W（将警告转为错误）无法捕获该类问题。

方案1：通过构建脚本日志校验（实现成本最低） #

在执行构建命令时，将输出日志重定向到文件，构建完成后检查日志中是否存在下载文件不可读的报错，存在则直接返回非0退出码终止流程，示例脚本如下：

#!/bin/bash
# 执行构建并保存日志
sphinx-build -M html . site -W 2>&1 | tee build.log
# 检查日志是否存在下载文件不可读的报错
if grep -q "download file not readable" build.log; then
    echo "检测到失效的下载文件引用，构建终止"
    exit 1
fi

方案2：在conf.py中添加自定义检查钩子（直接在构建流程中终止） #

在项目的conf.py文件末尾添加以下代码，会在构建过程中检查所有下载引用的文件是否存在，不存在则直接抛出错误终止构建：

import os
from sphinx.errors import SphinxError

def check_download_files(app, env):
    download_dir = os.path.join(app.outdir, 'downloads')
    # 遍历所有下载引用
    for filename in env.dlfiles:
        filepath = os.path.join(download_dir, filename.lstrip('/'))
        if not os.path.isfile(filepath):
            raise SphinxError(f"下载文件不存在: {filepath}")

def setup(app):
    app.connect('env-updated', check_download_files)

方案3：调整Sphinx日志级别配置 #

在conf.py中添加以下配置，将下载相关的日志级别提升为警告，这样-W参数就可以捕获该类问题并终止构建：

import logging
logging.getLogger('sphinx.util.download').setLevel(logging.WARNING)

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