我正在尝试记录一个稍微复杂的python包,其中包含几个私有子模块
即
package
+-- __init__.py "Package Initialization"
+-- _info.py "Package Info"
+-- _core.py "Packages Core members"
+-- _extra1.py "Package Extra members group 1"
然后在__init__.py
中,我有
from package._info import __authors__, __copyright__, __license__, \
__contact__, __version__, __title__, __desc__
from package._core import funcA, funcB, classA, classB
try:
from package._extra1 import funcE1A, funcE1B, funcE1C
except ImportError:
_extra1_requirement = "Requires external_package>=x.y"
def funcE1A(*args, **kwargs):
raise NotImplementedError(_extra1_requirement)
def funcE1B(*args, **kwargs):
raise NotImplementedError(_extra1_requirement)
def funcE1C(*args, **kwargs):
raise NotImplementedError(_extra1_requirement)
,以便所有公共成员都可以在package
名称空间中使用
但是,当我在sphinx中使用autosummary来记录我的包裹时,即
.. automodule:: package
Core Functions
--------------
.. autosummary::
:toctree: reference/
funcA
funcB
Core Classes
------------
.. autosummary::
:toctree: reference/
classA
classB
Extra 1 Functions
-----------------
.. autosummary::
:toctree: reference/
funcE1A
funcE1B
funcE1C
它会为reference/package.member
以及摘要表生成自动文档文件,但是如果我将文档更改为
.. automodule:: package
Core Functions
--------------
.. currentmodule:: package._core
.. autosummary::
:toctree: reference/
funcA
funcB
Core Classes
------------
.. currentmodule:: package._core
.. autosummary::
:toctree: reference/
classA
classB
Extra 1 Functions
-----------------
.. currentmodule:: package._extra1
.. autosummary::
:toctree: reference/
funcE1A
funcE1B
funcE1C
它会生成到文档页面的链接,但是这些页面现在被命名为reference/package.private_submodule.member
而不是reference/package.member
我想将主要文档页面保留为reference/package.member
,并自动汇总到这些页面的链接。但是,尽管进行了多次搜索并浏览了文档https://www.sphinx-doc.org/en/master/usage/extensions/autosummary.html
答案 0 :(得分:0)
我发现了问题
当我取出私有子模块时,我已经重命名了自动生成的文件,自动摘要已使用以下行生成了这些文件:
.. currentmodule:: package.submodule
此行是错误的根源,因为重构要求将其更改为:
.. currentmodule:: package
发现这一点后,我重命名了一些文件并重新运行构建,自动汇总生成的新文件已正确链接。