Sphinx警告‘Block quote未结束’在单行文档字符串中出现的原因

问题分析 #

你遇到的警告并非来自BIMIRecordInWrongLocation本身，而是源于Sphinx的自动文档继承机制：默认开启的autodoc_inherit_docstrings会让子类继承父类BIMIError的文档字符串。如果父类的docstring存在格式问题（比如用>标记的块引用结束后未添加空白行），哪怕子类用pass替代docstring，Sphinx仍会解析继承来的内容并抛出警告。

解决方案 #

1. 修复父类BIMIError的文档字符串格式
   找到BIMIError的定义，检查其docstring中的块引用内容，确保块引用结束后添加空白行再继续其他内容。示例修复：

   class BIMIError(Exception):
       """
       基础BIMI异常类
       
       > 注意：所有BIMI相关异常均继承此类
       
       用于统一处理BIMI解析过程中的错误
       """
   

2. 给子类显式添加空文档字符串
   用空的三引号文档字符串替代pass，避免继承父类有格式问题的docstring：

   class BIMIRecordInWrongLocation(BIMIError):
       """
       """
   

3. 关闭特定类的docstring继承
   如果不需要继承父类docstring，可在子类docstring开头添加:noindex:标记，或通过Sphinx配置调整，但优先推荐修复父类的格式问题。

内容的提问来源于stack exchange，提问作者Sean W.