python-sphinx - 如何在每个页面的侧边栏中包含目录树

Question

我正在 Sphinx 中生成 html 文档。

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

是否有捷径可寻？我将使用 readthedocs 来托管生成的文档，所以我宁愿避免使用任何第三方插件，除非它们在 readthedocs 上也可用。

Answer 1

您可以在conf.py.

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

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

您可以像这样将 localtoc.html 更改为conf.pyglobaltoc.html：

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

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

Answer 2

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

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

Answer 3

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

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

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

Glorious content.

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

More content


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

   index

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