严格模式下如何在Shell脚本中检测sphinx_build的警告？

Sphinx的sphinx-build默认在仅出现警告时会返回0退出码，没法直接用$?判断。要程序化检测警告，可以通过捕获构建输出并检查警告标识的方式实现，以下是修改后的脚本：

#!/usr/bin/env bash
rm -rf docs/build
BUILD_LOG="docs/build/sphinx_build.log"

# 执行文档构建，同时将输出保存到日志文件并实时显示在终端
sphinx-build -M html docs/source docs/build -E -n --keep-going 2>&1 | tee "$BUILD_LOG"
BUILD_EXIT_CODE=$?

# 检查日志中是否存在警告信息
if grep -q "WARNING:" "$BUILD_LOG"; then
    echo "⚠️ 检测到文档构建警告，请查看日志详情：$BUILD_LOG"
    # 这里添加警告触发的操作，比如不打开浏览器、发送提醒等
else
    # 无警告且构建成功时打开浏览器
    if [ $BUILD_EXIT_CODE -eq 0 ]; then
        sleep 1
        google-chrome docs/build/html/index.html
    else
        echo "❌ 文档构建失败，退出码：$BUILD_EXIT_CODE"
    fi
fi

关键说明： #

• 2>&1：将标准错误（Sphinx的警告通常输出到stderr）重定向到标准输出，确保警告信息能被捕获到日志文件
• tee "$BUILD_LOG"：同时将构建输出打印到终端和写入日志文件，兼顾实时查看和事后排查需求
• grep -q "WARNING:"：静默检查日志中是否包含警告标识，-q参数只返回结果不输出匹配内容，适合脚本内判断

备选方案（将警告转为错误） #

如果希望只要出现警告就让sphinx-build返回非零退出码，可以添加-W参数，把警告升级为错误：

sphinx-build -M html docs/source docs/build -E -n -W --keep-going

不过这个参数会让构建在遇到警告时终止（除非配合--keep-going，但部分场景下仍会导致构建失败），适合要求严格无警告的场景。

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