收集警告并让 Sphinx 提出警告

Question

def warn_undocumented_members(app, what, name, obj, options, lines):
    if what in MEMBERS_TO_WARN and not lines:
        sys.stderr.write("<autodoc> WARNING: {} is undocumented: {}\n".format(what, name))

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

是否有可能在 Sphinx 中冒出警告？

我查看了 if 子句中的 the app object but could not find anything satisfying. The only thing I found is raising a SphinxError，但这是停止构建而不是收集所有警告。此外，这也不符合 sphinx-build 的 -W 标志（我总是遇到硬错误）。

Answer 1

Sphinx 组件通过 logging facility, for which Sphinx defines custom adapters in sphinx.util.logging 传递警告。如果您使用那里提供的记录器，Sphinx 会将您的警告视为与它自己的警告相同，并遵守将它们变成错误的 -W 标志。

import sphinx
logger = sphinx.util.logging.getLogger('sphinx.ext.autodoc')

def warn_undocumented_members(app, what, name, obj, options, lines):
    if what in MEMBERS_TO_WARN and not lines:
        logger.warning(f'{what} is undocumented: {name}', type='autodoc')

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

收集警告并让 Sphinx 提出警告

Collect warnings and let Sphinx raise them

python

python-sphinx

autodoc