如何在Sphinx toctree中添加标题而不添加新文档？

Question

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

因此，我将我的autosummary指令分成了三个较小的指令，并在它们之间放置了一个隐藏的toctree，如下所示：

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的层次结构正是我想要的，但侧边栏缺少我的标题，它们没有显示出来。当我在任何这些隐藏的toctrees下添加一个像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或其他内容。我只想要字幕。如何实现？

- Jay Parthasarthy

---

你是否正在使用sphinx_rtd_theme？ - mzjn

是的，我正在使用那个主题。 - Jay Parthasarthy

Answer 1

toctree的目的是组织嵌套页面，并且它应该至少有一个条目（文件名）。否则，使用它没有任何意义。以下标记生成所需的侧边栏与sphinx_rtd_theme。我知道它不会给你想要的索引页面，但我想不出其他方法。将autosummary指令放在单独的文件中，并将每个文件添加为toctree条目。

.. toctree::
   :caption: Section 1

   autosummary1

.. toctree::
   :caption: Section 2

   autosummary2

- mzjn

---

这个解决方案对我的index.rst有什么影响？我猜用户不能像我希望的那样在一个页面上看到所有的类。 - Jay Parthasarthy

实际上，字面上来说，“不添加新文档”是问题标题的一部分。感谢您的帮助。 - Jay Parthasarthy

我只想让侧边栏的结构与我的主页结构相同。我不想要嵌套页面。如果在Sphinx-rtd中无法实现，那没关系。 - Jay Parthasarthy

我所要求的只是一种方法，使侧边栏结构与我的主页结构相匹配。一个人想在单个toctree中包含多个标题似乎并不疯狂。我只是放置了零条目的toctrees，试图在不重构整个主页的情况下插入标题- 这就是问题的要点。如果Sphinx不支持此选项，则可以直接说明。没有必要在评论中表现出那种语气。 - Jay Parthasarthy

@mzjn，这个不太清楚如何操作。autosummary文件需要有自己的页面吗？ - jay

@JayStanley：如果你需要帮助，请提出一个新问题。 - mzjn