使用self在sphinx中使用toctree创建站点地图似乎已损坏？

Question

我正在为一个相当大的项目更新常见问题解答，我想在页面顶部添加问题索引，这样用户就可以更轻松地找到他们正在寻找的内容。

Sphinx文档toctree article陈述“特殊条目名称self代表包含toctree指令的文档。如果您想从toctree生成”站点地图“，这非常有用。”这就是我想要的。问题是自我看起来很破碎，只包括当前的文件标题而不是字幕。当我在另一个文档并引用FAQ时它才能正常工作，只有文档本身才会失败。

演示

.. toctree::
   :maxdepth: 3

   faq

在

中的其他文件结果中

• 常见问题解答
  • FAQ
    • 问题1
    • 问题2
    • 问题3
  • 非显而易见的行为和其他需要知道

内部常见问题

.. toctree::
   :maxdepth: 3

   self

结果

• 常见问题

我想也许是因为当转换toctree并尝试将toctree移动到页面底部时，sphinx不知道字幕。没有变化。

关于如何在页面中使用sphinx包含页面索引的任何想法都将非常感谢

Answer 1

您正在寻找的是contents指令。

在页面标题后插入以下块以构建问题列表：

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

它会产生：

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