如何在Sphinx中只记录函数的子集

Question

使用Sphinx，我需要为我的Python应用程序生成两组文档：

1. 包含我的所有模块/函数
2. 仅包含我的模块中的函数子集

我想使用一个"；标签"；在函数docstring中，该字符串将指示是否将该函数包括在第二组文档中。

使用.. only，我能够根据我提供给sphinx构建的-t <tagname>来控制包含文档字符串的哪一部分。但是，我找不到任何方法来根据这些函数的文档字符串条目筛选出要包含在文档范围内的一组函数。

Answer 1

通常情况下，在发布问题后，您会得到答案。使用https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#skipping-成员并将以下代码放入conf.py

def include_only_tagged(app, what, name, obj, skip, options):
inclusion_tag_format = ".. only:: {}" #can be any pattern here, choose what works for you
for tag in app.tags.tags:
if obj.__doc__ is not None and inclusion_tag_format.format(tag) in obj.__doc__:
return False
return True

def setup(app):
if(len(app.tags.tags)>0):
app.connect('autodoc-skip-member', include_only_tagged)

因此，如果我使用类似".. only:: subset"的东西作为任何函数的文档字符串的一部分，也就是说，每当我运行sphinx-build -t subset时，只有这个函数会保留在生成的文档范围内。