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

Question

我正在使用带有autodoc扩展的sphinx，并且希望生成一个仅包含多个模块中未记录成员函数的列表，而不是记录成员。我可以成功地创建一个包含记录和未记录成员的列表，如下所示：

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

仅使用:members:指令将创建预期的文档成员列表。

.. automodule:: module
    :members:

但仅使用 :undoc-members: 指令（即省略 :members: 标志）不会生成任何列表：

.. automodule:: module
    :undoc-members:

有没有一种自动生成这个的方法？

（主要文档包括一个页面，显示所有记录的成员，但是我会发现，通过列出任何未记录的成员的单个页面来确保我已经为每个函数等编写了文档，而不显示那些已被记录的文本，会更加有用。）

- Bonlenfum

---

如果这是关于查找和记录这些未记录的成员，应该有一种在构建过程中自动列出它们的方式... 如果没有内置的方法，可以使用一个事件（autodoc-process-docstring），但需要编写自己的 Sphinx 扩展程序。 - user395760

好的，谢谢@delnan，我会考虑编写一个扩展。 - Bonlenfum

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

要打开（关闭）警告包括（排除）未记录成员，可以在conf.py中全局使用autodoc_default_flags，或者像问题中那样同时使用两个指令。

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

编辑：

我试图通过以下方法扩展此方法，仅生成未记录成员：

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

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

- Bonlenfum

---

这并没有完全回答我的问题，因为它仍然没有提供一种只生成未记录成员的页面的方法，但它确实提供了访问信息以查找（因此记录）它们的方式。 - Bonlenfum

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年中一直为此感到困惑，那么也许这会对您有所帮助？

- snazzybouche