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

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

我可以成功创建一个包含文档成员和未记录成员的列表,如下所示：

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

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

.. automodule:: module
    :members:

但仅使用：undoc-members：指令(即省略：members：flag)根本不会产生任何列表：

.. automodule:: module
    :undoc-members:

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

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

最佳答案

重写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: ","is undocumented: ","(%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);

要打开(关闭)警告,请在conf.py中使用autodoc_default_flags全局包含(排除)undoc-members,或者使用问题中的两个指令.

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

编辑：

我尝试通过以下方法扩展此方法以仅生成undoc成员：

>在函数warn_undocumented_members(上面)期间有条件地在对象上设置一个属性,比如warn_undoc = True
>将第二个覆盖函数附加到预处理程序事件autodoc-skip-member,如果它们没有设置warn_undoc,则跳过所有成员.

但是,进一步的调查规则是这种方法,因为在autodoc-process-docstring发生之前,每个成员组都会发生autodoc-skip-member.因此,根据文档字符串的存在/不存在,属性设置得太迟而无法有条件地跳过.