Sphinx生成纯文本报错：如何定位或跳过出错的.rst文件？

定位触发错误的.rst文件 #

• 关闭并行构建：执行make text SPHINXOPTS="-j 1"，串行构建会在报错时输出具体的文件路径，不会因为并行进程丢失错误上下文。
• 启用详细日志：添加-v参数执行make text SPHINXOPTS="-j 1 -v"，日志会逐行显示正在处理的文件，能直接定位到包含嵌套表格的文件。

跳过错误文件继续构建 #

修改项目的conf.py配置文件，添加以下设置让构建忽略非致命错误：

# 关闭严格模式，允许构建继续执行
strict = False

注意：该设置会忽略所有非致命错误，建议定位到问题文件后改回，避免掩盖其他潜在问题。

修复嵌套表格问题 #

找到问题文件后，有两种处理方式：

• 将嵌套表格拆分为多个独立表格，或者用列表搭配表格的形式替代嵌套结构，适配文本格式的限制。
• 若需要保留嵌套结构，可在.rst文件中用.. raw:: html嵌入原生HTML表格，文本构建时会跳过HTML内容，同时不影响HTML构建的正常显示。

处理sitemap提示信息 #

首行的sphinx-sitemap: No pages generated for sitemap.xml不是致命错误，是因为文本构建不会生成HTML页面，sitemap插件没有可处理的内容。可以在conf.py中针对文本构建禁用该插件：

from sphinx.util import logging

def setup(app):
    if app.builder.name == 'text':
        app.setup_extension('sphinx_sitemap')
        app.extensions['sphinx_sitemap'].enabled = False

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