在sphinx中使用self创建一个带有toctree的网站地图似乎被破坏了？

Question

我正在为一个相当大的项目更新FAQ，我想在页面顶部添加一个问题索引，这样用户就能更容易地找到他们要找的东西。

Sphinx文档 桐木条 州 "特殊条目名self代表包含toctree指令的文档。如果你想从toctree中生成一个 "sitemap"，这很有用。" 这就是我想要的。问题是，self似乎坏了，只包括当前文档的标题，而不是字幕。当我在另一个文档中并引用FAQ时，它可以正常工作，只有在文档本身中才会失败。

为了证明

.. toctree::
   :maxdepth: 3

   faq

在其他文件中的结果是

• 常问问题
  • 常见问题
    • 问题1
    • 问题2
    • 问题3
  • 不明显的行为和其他需要了解的情况

内部FAQ

.. toctree::
   :maxdepth: 3

   self

导致

• 常问问题

我想过可能是因为sphinx在转换toctree的时候没有意识到字幕的存在，于是尝试着把toctree移到页面底部。没有变化。

如果有任何关于如何用sphinx在页面本身中加入页面索引的想法，我将非常感激。

Answer 1

你要找的是 内容 指令。

在你的页面标题后插入以下代码块来建立问题列表。

.. contents::
   :local:
   :depth: 1

它将产生。

• 问题1
• 问题2
• 问题3