Python sphinx 文档 - 使用 autodocsumm 扩展的自动摘要链接不一致
我正在使用 Sphinx autodocsumm 扩展和以下自动摘要配置为 Python 项目生成文档，以在文档开头仅显示类的摘要。
Module1 module
----------------------------
.. automodule:: src.Module1
:members:
:undoc-members:
:show-inheritance:
:autosummary:
:autosummary-no-nesting:
在生成的 html 中，摘要类名称超链接不一致 - 一个是单独摘要存根文件的路径，而另一个仅引用主 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
我不明白为什么这些类在制作过程中受到不同的对待。第一个是一个有很多成员的大类，而第二个是一个只有几行的小类，所以生成存根文件可能有一些阈值？我的偏好是不引用单独的文件，而仅跳转到主文档中的相应锚点以获取所有摘要链接。
是否有一个设置来控制这种行为？
编辑：经过进一步审查，我认为这毕竟与 autodocsumm 没有任何关系。我注意到在执行“make html”后，仅为 Class1 文档创建一个子文件夹，而 Class2 仅在主 src.html 文件中引用。
project_path/docs/_build/html/src.Module1/src.Module1.Class1.html
project_path/docs/_build/html/src.html
那么...为什么这两个类的待遇不同呢？另外，是否有任何设置可以防止生成单独的文件夹和html文件？
I am generating documentation for a Python project using the Sphinx autodocsumm extension with the following autosummary configuration to show a summary of only classes at the beginning of the document.
Module1 module
----------------------------
.. automodule:: src.Module1
:members:
:undoc-members:
:show-inheritance:
:autosummary:
:autosummary-no-nesting:
In the generated html, the summary class name hyperlinks are not consistent -- one is a path to a separate summary stub file, while the other just references an anchor in the main src.html file.
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
I can't figure out why the classes are being treated differently during the make. The first one is a large class with many members while the second is a small class with just a few lines, so maybe there is some threshold for generating the stub file? My preference is to not reference a separate file and only jump to the respective anchor within the main document for all summary links.
Is there a setting to control this behavior?
Edit: Upon further review, I don't think this has anything to do with autodocsumm after all. I notice after doing the "make html" a subfolder is create only for the Class1 documentation while Class2 is referenced only in the main src.html file.
project_path/docs/_build/html/src.Module1/src.Module1.Class1.html
project_path/docs/_build/html/src.html
So... Why are these two classes treated differently? Also, is there any setting to prevent a separate folder and html file from being generated?
如果你对这篇内容有疑问，欢迎到本站社区发帖提问 参与讨论，获取更多帮助，或者扫码二维码加入 Web 技术交流群。
绑定邮箱获取回复消息
由于您还没有绑定你的真实邮箱，如果其他用户或者作者回复了您的评论，将不能在第一时间通知您！
发布评论
评论（1）
我终于解决了这个问题...在将我的项目缩小到最小可重现示例时，我注意到文档下的 src.Module1 文件夹仅包含 Class1 的第一个文件。
我不确定我做了什么来生成该文件夹，但在删除它并重建 Sphinx html 之后，我现在直接在 src.html 文件中获得了我期望的文档锚点：
I finally figured out the issue... While narrowing my project down to a minimum reproducible example, I noticed an src.Module1 folder under docs that had rst files for Class1 only.
I'm not sure what I did to produced that folder, but after deleting it and rebuilding the Sphinx html, I am now getting the document anchors I expect directly in the src.html file: