Sphinx遇Critical错误未终止构建，如何使其停止并报告失败？

要让Sphinx在遇到"Critical: unexpected section title"这类严重错误时终止构建并返回非0状态码，可以通过以下几种方式配置：

• 修改配置文件conf.py
  在项目的conf.py中添加或修改以下配置项，将所有警告视为错误，触发构建终止：

  warning_is_error = True
  

  这样只要Sphinx输出警告（包括你遇到的Critical级别的格式错误），都会直接终止构建，最终返回非0状态码。

• 命令行参数控制
  如果是通过sphinx-build命令行工具执行构建，添加-W参数即可实现相同效果：

  sphinx-build -W -b html docs/source docs/build
  

  要是你用Python代码调用Sphinx API，初始化Sphinx对象时传入warningiserror=True参数：

  from sphinx.application import Sphinx
  
  # 初始化Sphinx应用时开启警告转错误
  app = Sphinx(
      srcdir="docs/source",
      confdir="docs/source",
      outdir="docs/build",
      doctreedir="docs/build/.doctree",
      buildername="html",
      warningiserror=True
  )
  # 执行构建，遇到错误会终止并抛出异常
  app.build()
  

• 精细控制错误检查（可选）
  如果只需要针对特定类型的Critical错误终止构建，可以通过Sphinx的事件钩子自定义检查逻辑。在conf.py中添加以下代码：

  def check_unexpected_section_error(app, env):
      import logging
      # 获取Sphinx的日志记录器
      logger = logging.getLogger("sphinx")
      # 遍历日志记录，查找目标错误信息
      for record in logger.handlers[0].buffer:
          if record.levelname == "CRITICAL" and "unexpected section title" in record.getMessage():
              raise Exception("发现严重格式错误，终止构建")
  
  def setup(app):
      # 在构建一致性检查阶段触发自定义检查
      app.connect("env-check-consistency", check_unexpected_section_error)
  

  这种方式适合需要针对性拦截特定错误的场景，配合warning_is_error使用效果更佳。

内容的提问来源于stack exchange，提问作者O'Rooney