如何将toctree包含在每个页面的侧边栏中

Question

我正在Sphinx中生成html文档。

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

有一种简单的方法吗？我将使用readthedocs来托管生成的文档，所以我宁愿避免使用任何第三方插件，除非它们也可以在readthedocs上使用。

Answer 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。

Answer 2

包含'globaltoc.html'有一个缺点，即它不会显示您正在查看的页面的全局和本地toc。

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

Answer 3

除非您将要扫描以查找部分标题的文件名添加到toctree::中的.rst指令中，否则默认Sphinx侧边栏的“导航”部分中将不会显示任何内容。 {1}}文件。

例如，如果您希望index.rst文件的所有标题都出现在“导航”窗格中，则在index列表中写toctree::（不带扩展名），如下所示：< / p>

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

Glorious content.

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

More content


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

   index

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