Question

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

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

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

要打开（关闭）警告，请在autodoc_default_flags中使用conf.py全局包含（排除）undoc成员，或者同时使用问题中的两个指令。

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。因此，根据文档字符串的存在/不存在，属性设置得太晚而无条件跳过。

Answer 2

从Skipping Members，将其添加到您的conf.py：

def skip_non_undoc(app, what, name, obj, skip, options):
    # if undoc-members is set, show only undocumented members
    if 'undoc-members' in options and obj.__doc__ is not None:
        # skip member that have a __doc__
        return True
    else:
        return None

def setup(app):
    app.connect('autodoc-skip-member', skip_non_undoc)

使用选项members和undoc-members现在应该只显示未记录的成员。但是，无论您在何处使用undoc-members，它都将始终如此。如果在某些情况下只希望显示未记录的成员，而在某些情况下只希望显示两者，那么您将需要在该函数中实现一些更复杂的检查。

如果您在过去的6年中一直对此head之以鼻，也许这会有所帮助？

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

2 个答案: