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

【问题标题】：Connect Sphinx autodoc-skip-member to my function将 Sphinx autodoc-skip-member 连接到我的函数
【发布时间】：2010-09-21 05:22:08
【问题描述】：

我想使用sphinx's 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)

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

【问题讨论】：

标签： python python-sphinx autodoc

【解决方案1】：

啊哈，谷歌搜索的最后努力出现了this example，向下滚动到底部。显然 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)

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

【讨论】：

【解决方案2】：

这个答案扩展了answer by 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)

【讨论】：

【解决方案3】：

如果有人来搜索相同的问题，但搜索的是 AutoAPI 而不是 autodoc，则以下 sn-p 成功地从 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)

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

这包括在检测以 _ 开头的方法时添加如下内容：

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

【讨论】：