python - 我怎样才能用 sphinx/autodoc 列出未记录的成员？

Question

我正在使用 sphinx 和 autodoc 扩展，并且想生成一个列表仅包含几个模块中未记录的成员函数，而不是记录在案的成员。

我可以成功地创建一个包含记录成员和未记录成员的列表，如下所示:

.. 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));

然后将此函数连接到事件(来自 this SO thread 中的答案):

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

要打开(关闭)警告，包括(排除)undoc-members——全局使用 conf.py 中的 autodoc_default_flags，或者使用两个指令，如问题。

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

编辑:

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

• 在函数 warn_undocumented_members 期间有条件地设置对象的属性，例如 warn_undoc=True(上文)
• 将第二个覆盖函数附加到预处理器事件 autodoc-skip-member，如果它们没有设置warn_undoc，则跳过所有成员。

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