如何将本地目录包含到 Sphinx 文档中？答案

【问题标题】：How to include a local table of contents into Sphinx doc?如何将本地目录包含到 Sphinx 文档中？
【发布时间】：2014-07-30 12:52:41
【问题描述】：

如何将本地目录包含到 Sphinx 文档中？

我试过了

.. toc::

但这似乎没有任何效果：文档中没有插入任何内容。

基本上，我需要将指向当前页面中各个部分的链接放置在每个页面的特定位置。

这可能吗？

【问题讨论】：

【解决方案1】：

我不能 100% 确定这是您要查找的内容，但 .. contents:: 指令可能会有所帮助。默认情况下，无论您将指令放在何处，它都会为您提供整个页面的标题。指定:local: 后，它将为您放置指令的下面的标题生成一个本地目录（对于小节目录很方便）。

.. contents:: Table of Contents
    :depth: 3

【讨论】：

.. contents:: :local: 是神奇的果汁。当省略:local: 标志时，目录前面会无用地添加到文档标题的链接。此外，所有其他标题都是文档标题的子标题，因此无用的缩进比原本应该缩进的级别更深。简而言之，:local: 对于大多数用例来说几乎是强制性的。（坦率地说，我真的希望 :local: 是默认值。）
:local: 关键字仍然有效吗？我无法让它在最新版本的 sphinx 上运行，它似乎只在 H1 标题下工作，而不是在部分中。
据我所知，是的。我已经在 Sphinx 3.5.2 中的 H2 下对其进行了测试。

【解决方案2】：

我有更多的运气：

.. contents:: Table of Contents
   :depth: 1
   :local:
   :backlinks: none

反向链接摆脱了从标题返回到目录的烦人链接。

【讨论】：