2

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

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

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

我正在使用这个流程来生成 HTML 文档：

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

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

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)
4

1 回答 1

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 ...
于 2021-10-20T12:09:33.257 回答