8

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

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

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

正如预期的那样，单独使用该:members:指令仅创建记录成员的列表。

.. automodule:: module
    :members:

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

.. automodule:: module
    :undoc-members:

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

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

4

2 回答 2

6

通过将以下内容添加到以下内容，覆盖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-members - 全局使用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发生。因此，属性设置得太晚，无法根据文档字符串的存在/不存在有条件地跳过。

于 2013-01-09T15:16:56.233 回答
0

从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 年中一直在为此摸不着头脑，也许这会有所帮助？

于 2019-08-22T14:19:06.063 回答