Sphinx Autodoc 删除空的子模块和包答案

【问题标题】：Sphinx Autodoc remove empty submodules and packagesSphinx Autodoc 删除空的子模块和包
【发布时间】：2020-12-06 07:48:49
【问题描述】：

我正在尝试使用 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)

【问题讨论】：

一种选择是调整 sphinx-apidoc 的输出，然后将要保留的 *.rst 文件添加到源代码管理中。每次要生成文档时都不需要运行 sphinx-apidoc。见stackoverflow.com/a/28481785/407651。

标签： python python-sphinx autodoc sphinx-apidoc

【解决方案1】：

当您运行 sphinx-apidoc 时，它会使用预先确定的选项运行，这些选项是“members”、“undoc-members”、“show-inheritance”。这些可以在生成的 .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 ...

【讨论】：