函数在 Sphinx autodoc 生成的文档中出现两次

Question

背景信息

我通过 Sphinx autodoc 从文档字符串生成文档。源文件 mypackage/mypackage.py 中有一个函数 mypackage.mypackage.foo()。它在 __init__.py 中隐式导入，因此用户可以将其用作 mypackage.foo()。

我确实操作了 Sphinx autodoc，它生成了 foo() 的文档，尊重它们的导入方式。这有效。

问题

关于foo()的文档生成了两次；一次为 mypackage.foo()，一次为 mypackage.mypackage.foo()。

详细信息

这是项目的结构：

mypackage
├── a.py
├── __init__.py
└── mypackage.py

__init__.py 执行导入，然后操作__all__变量：

from .mypackage import *
__all__ = ['foo']  # for alternative see: https://stackoverflow.com/a/66996523/4865723

以及mypackage/mypackage.py 定义 foo()。

因此，我可以做这样的事情：

import mypackage
mypackage.foo()

相关问题和解答

以下是带我进入当前“部分解决方案”的问题和答案。其中 mypackage.foo() 按文档中的预期显示，但 mypackage.mypackage.foo() 不会消失。

• autodoc：基类以全名显示，而不是尊重导入
• 如何在没有模块名称的情况下记录类？

Answer 1

@mzjn 给了我正确的方向。他是正确的，有两个 automodule 指令。因此，我们的目标是让 sphinx-apidoc（生成指令）忽略 mypackage/mypackage.py。

为此，使其成为“私有模块”，并修改其文件名以下划线（_）开头。

由此产生的项目结构：

mypackage
├── a.py
├── __init__.py
└── _mypackage.py

并且__init__.py中的导入需要修改为from ._mypackage import *。