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

Question

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

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

展示

.. toctree::
   :maxdepth: 3

   faq

在其他文件中导致

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

内部常见问题

.. toctree::
   :maxdepth: 3

   self

结果是

• 经常问的问题

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

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

Answer 1

您正在寻找的是内容指令.

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

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

它会产生:

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