Question

我想使用sphinx's autodoc-skip-member事件来选择某个python类中的一部分成员来获取文档。

但是从sphinx文档中不清楚，我找不到任何说明的例子：我在哪里放置代码来连接它？我看到Sphinx.connect并且我怀疑它出现在我的conf.py中，但是当我在conf.py中尝试使用此代码的变体时，我找不到应该连接的应用程序对象（）：

def maybe_skip_member(app, what, name, obj, skip,
                                  options):
    print app, what, name, obj, skip, options
    return False

# This is not even close to correct:
#from sphinx.application import Sphinx
#Sphinx().connect('autodoc-skip-member', maybe_skip_member)

指向一个简单示例的指针是理想的。

Answer 1

啊哈，最后一次用谷歌搜索的努力转向this example，向下滚动到底部。显然，conf.py中的setup（）函数将通过app调用。我能够在conf.py的底部定义以下内容：

def maybe_skip_member(app, what, name, obj, skip, options):
    print app, what, name, obj, skip, options
    return True

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

这显然是无用的（它会跳过所有内容），但这是我寻找的最小例子，却找不到......

Answer 2

这个答案扩展到answer by bstpierre。以下是我conf.py的相关部分：

autodoc_default_flags = ['members', 'private-members', 'special-members',
                         #'undoc-members',
                         'show-inheritance']

def autodoc_skip_member(app, what, name, obj, skip, options):
    exclusions = ('__weakref__',  # special-members
                  '__doc__', '__module__', '__dict__',  # undoc-members
                  )
    exclude = name in exclusions
    return skip or exclude

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

Answer 3

如果有人来搜索相同的问题，但使用的是 AutoAPI 而不是 autodoc，下面的代码段成功地从 AutoAPI 生成的文档中排除了以 _ 开头的所有属性和方法；这在实践中并不是一个好主意，但我想从一些非常容易检测的东西开始。

def autoapi_skip_member(app, what, name, obj, skip, options):
    """Exclude all private attributes, methods, and dunder methods from Sphinx."""
    import re
    exclude = re.findall('\._.*', str(obj))
    return skip or exclude


def setup(app):
    """Add autoapi-skip-member."""
    app.connect('autoapi-skip-member', autoapi_skip_member)

要指出的一个怪癖/奇怪的是，在 name 函数中应用于 str(obj) 而不是 autoapi_skip_member 的相同函数似乎不起作用，而我（显然) 错误地认为是同一件事（根据 AutoAPI 文档为“fully qualified name of the object”）。

这包括在抛出类似以下内容以检测以 _ 开头的方法时：

or (hasattr(obj, '__name__') and str(obj.__name__).startswith('_'))

将Sphinx autodoc-skip-member连接到我的函数

3 个答案: