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

Question

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

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

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或其他什么。我只想要字幕。我该怎么做呢？

标签： pythonpython-sphinxrestructuredtexttoctree

Answer 1

a 的目的toctree是组织嵌套页面，它应该至少有一个条目（文件名）。否则，使用它实际上没有任何意义。

下面的标记使用 sphinx_rtd_theme 生成所需的侧边栏。我意识到它不会为您提供您想要的索引页面，但我想不出任何其他方式来做到这一点。将autosummary指令放在单独的文件中，并将每个文件添加为toctree条目。

.. toctree::
   :caption: Section 1

   autosummary1

.. toctree::
   :caption: Section 2

   autosummary2