Sphinx 自动摘要链接到导入的成员文档答案

【问题标题】：Sphinx autosummary link to imported member documentationSphinx 自动摘要链接到导入的成员文档
【发布时间】：2019-03-27 08:08:05
【问题描述】：

我正在尝试记录一个有点复杂的 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

，但我仍然无法找到任何帮助

【问题讨论】：

标签： python package python-sphinx toctree

【解决方案1】：

我发现了问题

当我取出私有子模块时，我已经重命名了自动生成的文件，autosummary 用以下行生成了这个文件：

.. currentmodule:: package.submodule

此行是错误的来源，因为重构需要将其更改为：

.. currentmodule:: package

发现这一点后，我重命名了几个文件并重新运行构建，自动摘要生成的新文件已正确链接。

【讨论】：