python - Sphinx Autodoc 删除空的子模块和包

Question

我正在尝试使用 sphinx 来为我的项目创建文档，它是一组划分为项目内部模块的函数。

我只需要在文档中公开一小部分函数，​​所以我使用 autodoc-skip-member 通过标记文档字符串来过滤掉不需要的内容，它似乎可以通过没有列出不需要的功能，但我最终得到了一堆空模块和子模块。

有没有办法告诉 sphinx 不要列出空模块？我假设我可以使用 exclude 功能，但它不会是一个自动添加新代码的过程，我将不得不一直维护排除列表。

我正在使用此流程生成 HTML 文档:

sphinx-apidoc -f -e -M -o source/ ../src/
sphinx-build source/ build/

这是过滤掉 conf.py 文件中函数的代码，即使它在最终 HTML 文档中列出的模块上返回 True 也是如此。

def include_only(app, what, name, obj, skip, options):
    if obj.__doc__ is not None and "::public" in obj.__doc__:
        return False
    return True


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

Answer 1

当您运行 sphinx-apidoc 时，它会使用预先确定的选项运行，这些选项是“成员”、“undoc-成员”、“显示继承”。这些可以在生成的 .rst 文件中看到，因为您会看到类似这样的内容:

.. automodule:: module
   :members:
   :undoc-members:
   :show-inheritance:

将“undoc-members”作为选项，autodoc 会将空模块添加到您的文档中。为了解决这个问题，当您运行 sphinx-apidoc 时，您只需在前面添加 SPHINX_APIDOC_OPTIONS=members,show-inheritance(加上您希望包含的任何其他 autodoc 选项)，即

SPHINX_APIDOC_OPTIONS=members,show-inheritance sphinx-apidoc ...