Блог

Я использую строку autodoc-process-docstring для проверки наличия недокументированных участников

 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)
 

Есть ли какая-либо возможность выдать предупреждения в Сфинксе?

Я заглянул в объект приложения, но не смог найти ничего удовлетворяющего. Единственное, что я обнаружил, — это ошибка SphinxError в предложении if, но это останавливает сборку вместо сбора всех предупреждений. Также это не соответствует -W флагу sphinx-build (у меня всегда есть жесткая ошибка).

Компоненты Sphinx передают предупреждения через logging средство, для которого Sphinx определяет пользовательские адаптеры 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)