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

Question

我想用 sphinx的autodoc-skip-member 事件来选择某个Python类中的一部分成员进行文档编写。

但是在sphinx的文档中没有明确说明，我也找不到任何示例来说明：我应该把代码放在哪里来连接这个事件？我看到有 Sphinx.connect，我怀疑这个代码应该放在我的conf.py文件里，但当我在conf.py中尝试不同的代码时，我找不到应该连接的app对象：

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

如果有人在找关于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)

有一个小问题需要提一下，就是在autoapi_skip_member这个函数里，用name代替str(obj)似乎不起作用。我之前误以为这两者是一样的（根据AutoAPI文档，‘对象的完全限定名称’）。

这也包括像下面这样的代码，用来检测以_开头的方法：

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

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

啊哈，最后一次努力在网上搜索找到了这个例子，往下滚动到最底部。显然，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)

这显然是没用的（它跳过了所有内容），但这正是我一直在寻找的最简单的例子，却一直找不到...