如何让Sphinx正确收集并抛出autodoc检测到的未文档化成员警告

解决方案 #

Sphinx 提供了原生的警告输出接口，输出的警告会自动被Sphinx的警告收集体系捕获，完美兼容sphinx-build的-W（警告转错误）、--keep-going等参数，也会被计入最终构建报告的警告统计里。

适配后的代码示例 #

import sys
from sphinx.util import logging

# 你自定义的需要检测的成员类型列表
MEMBERS_TO_WARN = {"function", "class", "method", "attribute"}

logger = logging.getLogger(__name__)

def warn_undocumented_members(app, what, name, obj, options, lines):
    if what in MEMBERS_TO_WARN and not lines:
        # 调用Sphinx封装的logger输出警告
        logger.warning(f"<autodoc> WARNING: {what} is undocumented: {name}", location=name)

def setup(app):
    app.connect('autodoc-process-docstring', warn_undocumented_members)

实现说明 #

• 使用sphinx.util.logging下的logger输出的警告会自动纳入Sphinx的原生警告处理流程，不需要手动往sys.stderr写内容
• 可选传入location参数，可以让警告输出时带上对应的文件/成员位置信息，方便定位问题
• 如果你使用的是Sphinx 2.x及更早版本，也可以直接在事件回调里调用app.warn()方法输出警告，效果一致：

  def warn_undocumented_members(app, what, name, obj, options, lines):
      if what in MEMBERS_TO_WARN and not lines:
          app.warn(f"<autodoc> WARNING: {what} is undocumented: {name}", location=name)
  

• 该方案不会中断构建流程，会收集所有符合条件的警告后统一输出，同时完全兼容-W参数：当开启-W时所有这类警告会被转为错误终止构建，未开启时仅作为警告展示。

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