Python sphinx 文档 -- 使用 autodocsumm 扩展的自动摘要链接不一致

Question

我正在使用 Sphinx autodocsumm 扩展和以下自动摘要配置为 Python 项目生成文档，以便在文档开头仅显示 classes 的摘要。

 Module1 module
----------------------------

.. automodule:: src.Module1
   :members:
   :undoc-members:
   :show-inheritance:
   :autosummary:
   :autosummary-no-nesting:

在生成的 html 中，摘要 class 名称超链接不一致 -- 一个是指向单独的摘要存根文件的路径，而另一个只是引用主 src.html 文件.

file:///project_path/docs/_build/html/src.Module1/src.Module1.Class1.html#src.Module1.Class1
file:///project_path/docs/_build/html/src.html#src.Module1.Class2

我不明白为什么 classes 在制作过程中受到不同对待。第一个是有很多成员的大class，而第二个是只有几行的小class，所以生成存根文件可能有一些门槛？我的偏好是不引用单独的文件，只跳转到主文档中所有摘要链接的相应锚点。

是否有控制此行为的设置？

编辑：经过进一步审查，我认为这毕竟与 autodocsumm 没有任何关系。我注意到在执行“make html”后，仅为 Class1 文档创建了一个子文件夹，而仅在主 src.html 文件中引用了 Class2。

project_path/docs/_build/html/src.Module1/src.Module1.Class1.html
project_path/docs/_build/html/src.html

所以...为什么这两个 class 会受到不同的对待？另外，是否有任何设置可以防止生成单独的文件夹和 html 文件？

Answer 1

我终于弄清楚了问题...在将我的项目缩小到最小的可重现示例时，我注意到文档下的 src.Module1 文件夹仅包含 Class1 的第一个文件。

Project
    docs
        _build
        src.Module1
            Module1.Class1.rst
            src.Module1.Class1.rst

我不确定我做了什么来生成那个文件夹，但是在删除它并重建 Sphinx html 之后，我现在直接在 src.html 文件中获得了我期望的文档锚点:

file:///project_path/docs/_build/html/src.html#src.Module1.Class1
file:///project_path/docs/_build/html/src.html#src.Module1.Class2

Python sphinx 文档 -- 使用 autodocsumm 扩展的自动摘要链接不一致

Python sphinx documentation -- autosummary links not consistent using autodocsumm extension

python

documentation

docstring

python-sphinx