如何在每个页面的侧边栏中包含目录树答案

【问题标题】：How to include the toctree in the sidebar of each page如何在每个页面的侧边栏中包含目录树
【发布时间】：2013-09-28 22:19:42
【问题描述】：

我正在 Sphinx 中生成 html 文档。

如何修改文档中每个 html 页面的侧边栏，以便它们包含目录树？默认情况下，目录树似乎只显示在master_doc 页面中，并且只显示在主区域而不是侧边栏中。

有没有简单的方法来做到这一点？我将使用 readthedocs 来托管生成的文档，因此我宁愿避免使用任何第三方插件，除非它们在 readthedocs 上也可用。

【问题讨论】：

标签： python-sphinx sidebar toctree

【解决方案1】：

您可以在conf.py 中自定义您的 html 侧边栏。

默认的 html 侧边栏包含 4 个模板：

['localtoc.html', 'relations.html', 'sourcelink.html', 'searchbox.html']

在conf.py 中，您可以将 localtoc.html 更改为 globaltoc.html，如下所示：

html_sidebars = { '**': ['globaltoc.html', 'relations.html', 'sourcelink.html', 'searchbox.html'] }

由于这最终将在 HTML 文件中使用，这应该适用于 ReadTheDocs。

【讨论】：

【解决方案2】：

包含“globaltoc.html”的一个缺点是它不会同时显示您正在查看的页面的全局和本地目录。

似乎其他人对此限制感到厌烦，并导致后续开发扩展以支持侧边栏中的完整目录，结帐：https://pypi.python.org/pypi/sphinxcontrib-fulltoc

【讨论】：

这很好用！但我必须先pip install --upgrade setuptools，否则安装失败并出现一个奇怪的错误：AttributeError: '_NamespacePath' object has no attribute 'sort'
我目前在 readthedocs 尝试安装时收到此错误报告。
@Chris 我怀疑github.com/sphinx-contrib/fulltoc/issues/14 是造成这种情况的原因，我会尽快调查。

【解决方案3】：

在您将要扫描的部分标题的文件名添加到 .rst 中的 toctree:: 指令之前，默认 Sphinx 侧边栏的“导航”部分中不会出现任何内容文件。

例如，如果您希望 index.rst 文件的所有标题都显示在导航窗格中，请在 toctree:: 列表中写入 index（不带扩展名），如下所示：

My Level 1 Heading
==================

Glorious content.

My Level 2 Heading
------------------

More content


.. toctree::
   :maxdepth: 2
   :caption: Contents:

   index

关键是在最后添加index。如果您像我一样，您可以使用来自 sphinx-quickstart 的自动生成模板开始您的项目，该模板（在撰写本文时）使用 EMPTY 目录树填充您的 .rst 文件。

【讨论】：