如何使用sphinx/autodoc列出未记录的成员？

Question

我正在使用带有autodoc扩展的sphinx,并希望生成一个仅包含几个模块中未记录的成员函数的列表,而不是文档化的成员.

我可以成功地创建一个包含列表都文档化成员和无证成员名单如下:

.. automodule:: module
    :members:
    :undoc-members:

仅使用该:members:指令就可以按预期创建记录成员的列表.

.. automodule:: module
    :members:

但仅使用:undoc-members:指令(即​​省略:members:标志)不会导致任何列表:

.. automodule:: module
    :undoc-members:

有没有办法自动生成这个？

(主要文档包含一个显示所有文档成员的页面,但我发现通过使用单个页面列出任何未记录的成员来确保我为每个函数编写文档更有用,而不显示那些文档记录的).

Answer 1

覆盖autodoc-process-docstring事件（如@delnan 所述）可以提供帮助，方法是将以下内容添加到conf.py：

# set up the types of member to check that are documented
members_to_watch = ['function',];

def warn_undocumented_members(app, what, name, obj, options, lines):
    if(what in members_to_watch and len(lines)==0):
        # warn to terminal during build
        print "Warning: ", what, "is undocumented: ", name, "(%d)"% len(lines);
        # or modify the docstring so the rendered output is highlights the omission
        lines.append(".. Warning:: %s '%s' undocumented" % (what, name));

然后将此函数连接到事件（来自此 SO 线程中的答案）：

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

要打开（关闭）警告，请包括（排除） undoc 成员——全局使用autodoc_default_flagsin conf.py，或使用两个指令，如问题中所述。

autodoc_default_flags = ['members', 'undoc-members' ]
#autodoc_default_flags = ['members' ]

编辑：

我试图通过以下方法扩展这种方法以仅生成 undoc 成员：

• warn_undoc=True在函数期间有条件地在对象上设置一个属性，例如，，warn_undocumented_members（上图）
• 附加第二重载函数的预处理事件autodoc-skip-member是跳过所有成员，如果他们不已经warn_undoc设置。

然而，进一步的调查排除了这种方法，因为autodoc-skip-member发生在每组成员之前autodoc-process-docstring发生。因此，属性设置得太晚了，无法根据文档字符串的存在/不存在有条件地跳过。