函数在 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 执行 import 然后操作 __all__ 变量：

from .mypackage import *
__all__ = ['foo']  # for alternative see: 

而 mypackage/mypackage.py 定义 foo()。

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

import mypackage
mypackage.foo()

相关问答

以下是将我带到当前“部分解决方案”的问题和答案。 mypackage.foo() 按预期出现在文档中，但 mypackage.mypackage.foo() 没有消失。

• How do I document classes without the module name?

Answer 1

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

为了使它成为一个“私有模块”，修改它的文件名以下划线开头 (_)。

生成的项目结构：

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

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