能否通过Sphinx抑制‘Unexpected indentation’错误或指定文件警告？

问题背景 #

项目中的license.rst通过以下方式引入许可证文件：

License
=======

.. include:: ../LICENSE.txt

但LICENSE.txt的列表缩进格式不符合RST规范：

Copyright ...

... provided that the following conditions are met:
   *  Foo
      bar.
   *  Baz
      bee.
   *  Bop
      bow.
 
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" ...

触发Sphinx错误：../LICENSE.txt:7: ERROR: Unexpected indentation.，原因是include指令默认将引入的文件当作RST格式解析。

现有方案的局限 #

• 使用:literal:或:code:参数可修复错误，但会将许可证内容渲染为代码块，大幅改变网站样式，需征得客户同意，流程繁琐。
• 曾通过suppress_warnings = ["etoc.toctree"]抑制过其他警告，但该缩进错误未明确标注所属警告类型，直接添加相关内容不符合Sphinx配置规范。

可行的解决方法 #

1. 自定义日志过滤器抑制特定错误 #

在项目的conf.py中添加自定义过滤逻辑，精准屏蔽来自LICENSE.txt的缩进错误：

from sphinx.util import logging

def setup(app):
    logger = logging.getLogger('sphinx')
    def filter_license_errors(record):
        msg = record.getMessage()
        # 匹配目标错误信息与文件路径
        if 'Unexpected indentation' in msg and '../LICENSE.txt' in msg:
            return False  # 过滤该日志记录
        return True
    logger.addFilter(filter_license_errors)

该方法不会改变页面样式，也无需修改许可证文件内容。

2. 调整LICENSE.txt的缩进以符合RST规范 #

如果允许修改许可证文件，可将列表项的二级缩进调整为4个空格（RST标准缩进）：

... provided that the following conditions are met:
   *  Foo
    bar.
   *  Baz
    bee.
   *  Bop
    bow.

此方法从根源解决错误，无需额外配置，但需确认许可证文件的修改不会引发合规问题。

3. 使用raw指令保留原格式引入（仅HTML输出适用） #

若想保持原格式同时避免RST解析错误，可将include指令包裹在raw块中：

License
=======

.. raw:: html

    .. include:: ../LICENSE.txt

注意该方法仅对HTML构建有效，若需支持PDF等其他输出格式则不适用。

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