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

【问题标题】：How to add captions in Sphinx toctree without adding new documents?如何在不添加新文档的情况下在 Sphinx 目录树中添加标题？
【发布时间】：2020-04-07 04:01:58
【问题描述】：

好的，我正在使用 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 或其他任何内容。我只想要字幕。我该怎么做？

【问题讨论】：

你在使用 sphinx_rtd_theme 吗？
是的，我正在使用那个主题。

标签： python python-sphinx restructuredtext toctree

【解决方案1】：

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

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

.. toctree::
   :caption: Section 1

   autosummary1

.. toctree::
   :caption: Section 2

   autosummary2

【讨论】：

这个解决方案对我的 index.rst 有什么影响？我假设用户无法像我希望的那样在一页上看到所有课程。
实际上，它确实是......“不添加新文档”是问题标题的一部分。感谢您的帮助。
我希望侧边栏结构能够反映我的主页结构。我不想要嵌套页面。如果这在 Sphinx-rtd 中是不可能的，无论如何。
我所要求的只是一种使侧边栏结构与我的主页结构相匹配的方法。一个人可能想在一个目录树中包含多个标题似乎并不疯狂。我只放了零条目的目录树来尝试破解标题，而不重构我的整个主页——问题的重点。如果 Sphinx 不支持此选项，那么您可以这样说。不需要你评论的语气。