如何让sphinx-build在文件缺失或指令配置错误时抛出错误？

核心结论 #

Sphinx 7.x版本已修复literalinclude指令的静默错误问题——当目标文件不存在、指令名称拼写错误或参数配置有误时，执行sphinx-build会明确输出对应的错误/警告信息，无需依赖-vvv参数也能快速定位问题根源。

6.2.1版本临时解决方案 #

若暂时因主题限制无法升级，可通过以下方式强制暴露问题：

1. 配置文件修改：在conf.py中添加一行配置，将警告转为错误，终止构建并输出详情：

warning_is_error = True

2. 命令行参数替代：无需修改配置，直接在构建命令中加入-W参数（效果等同于上述配置）：

sphinx-build -W -b html mydocs docscompiled

原因说明 #

Sphinx 6.2.1中，literalinclude的错误默认以警告形式输出，而默认构建逻辑不会因警告终止进程；再加上sphinx_rtd_theme不会在生成的页面中展示这类警告，导致问题被隐藏。启用warning_is_error后，这类问题会直接触发构建失败，强制你关注并修复。

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