python - 如何在不添加新文档的情况下在 Sphinx toctree 中添加标题？

Question

好的，我正在使用 Sphinx Autosummary 为某些类生成文档。有三种不同类型的类，我希望我的边栏有三个不同的部分，就像我在 toctree 指令中使用 :caption: 选项一样。

所以我添加了将我的自动摘要指令分成三个较小的指令，并且我在它们之间放置了一个隐藏的目录树，如下所示:

Section 1

.. toctree::
   :hidden:
   :caption: Section 1

.. autosummary
   :toctree: stubs

   myclass
   anotherclass


Section 2

.. toctree::
   :hidden:
   :caption: Section 2

.. autosummary::
   :toctree:

   thirdclass

产生一个像这样的侧边栏:

myclass
anotherclass
thirdclass

这行不通。我的 index.html 的层次结构正是我想要的样子，但侧边栏缺少我的字幕，它们没有显示。当我在任何这些隐藏目录树下添加一个像 self 这样的页面时，标题会显示:

Section 1

.. toctree::
   :hidden:
   :caption: Section 1

   self

.. autosummary
   :toctree: stubs

   myclass
   anotherclass


Section 2

.. toctree::
   :hidden:
   :caption: Section 2

.. autosummary::
   :toctree:

   thirdclass

产生一个像这样的侧边栏:

SECTION 1 (caption)
Documentation Home
myclass
anotherclass
thirdclass

这就是我要找的东西，但我不想引用 self 或其他任何内容。我只想要字幕。我该怎么做？

Answer 1

toctree 的目的是组织嵌套页面，它应该至少有一个条目(文件名)。否则，使用它真的没有任何意义。

下面的标记使用 sphinx_rtd_theme 生成所需的侧边栏。我知道它不会给你你想要的索引页，但我想不出任何其他方法。将 autosummary 指令放在单独的文件中，并将每个文件添加为 toctree 条目。

.. toctree::
   :caption: Section 1

   autosummary1

.. toctree::
   :caption: Section 2

   autosummary2