问题描述
我需要 Sphinx 自动摘要扩展来使用 :toctree: generated/
生成存根,但我也想防止 TOC 条目出现在 HTML 侧栏中。考虑以下文档字符串:
MySubPackage (mypackage.mysubpackage)
=====================================
Some Title
----------
.. currentmodule:: mypackage.mysubpackage
Some description
.. toctree::
:hidden:
:maxdepth: 1
mypackage.mysubpackage.mysubsubpackage1
mypackage.mysubpackage.mysubsubpackage2
Sub-Packages
------------
.. autosummary::
:toctree: generated/
mysubsubpackage1
mysubsubpackage2
每个 subsubpackage
包含更多私有的 subsubsubpackages
,其类和方法在 subsubpackage
的 __init__.py
文件的文档字符串中公开。 autosummary
成功地为这些 subsubpackages
中的所有类和函数生成存根文件,但不为中间包生成存根 .rst 文件。最后,我留下了缺失的存根文件,如果没有这些存根文件,既不存在 TOC 条目,也不存在子子包的类和方法的模块路径。使用 Sphinx 的 .. toctree::
指令通过生成中间存根文件解决了一半的问题。但是,我最终在侧边栏 TOC 中得到了重复的条目。我所需要的只是使自动摘要生成中间存根文件或使用某种自动摘要选项,如 :hiddentoc:
以便它保留生成的存根文件但不添加到 TOC 的条目。我对 Sphinx 比较陌生,我尝试仅使用文档字符串来自动化文档生成过程。
非常感谢!
解决方法
问题解决了!对于遇到类似问题的任何人,请继续阅读。
该问题是由于在子包的 :toctree: generated/
文件中重复使用了 __init__.py
选项引起的。它导致自动摘要扩展创建嵌套的 /generated/generated/..
目录,因此无法找到 *.stub 文件。删除输出目录路径并将其保留为简单的 :toctree:
后,问题解决了,无需使用额外的 .. toctree::
和 .. autosummary::
指令。