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

Question

我想使用 sphinx 的 autodoc-skip-member 事件来选择某个 python 类上的部分成员用于文档。

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

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

啊哈，谷歌搜索的最后努力出现了这个例子，向下滚动到底部。显然，conf.py 中的 setup() 函数将被应用程序调用。我能够在 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

这个答案扩展了 bstpierre 的答案。它实现了

autodoc-skip-member

。以下是我的相关部分

conf.py

:

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

def autodoc_skip_member(app, what, name, obj, skip, options):
    # Ref: https://stackoverflow.com/a/21449475/
    exclusions = ('__weakref__',  # special-members
                  '__doc__', '__module__', '__dict__',  # undoc-members
                  )
    exclude = name in exclusions
    # return True if (skip or exclude) else None  # Can interfere with subsequent skip functions.
    return True if exclude else None
 
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

的相同函数似乎不起作用，我（显然）错误地认为这是相同的thing（“对象的完全限定名称”，根据 AutoAPI 文档）。

这包括添加如下内容来检测以

_

开头的方法：

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

Answer 4

使用

autodoc-skip-member

是跳过模块的单个成员的正确方法（请参阅其他答案），但是如果您想跳过整个模块，则可以在运行 autodoc 时传递排除模式：

sphinx-apidoc -o docs src '*skip_this*'