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

Question

我正在使用Sphinx生成HTML文档。

如何修改每个HTML页面的侧边栏，使其包括toctree？默认情况下，toctree似乎只在master_doc页面中显示，并且仅在主区域而不是侧边栏中显示。

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

- Travis Bear

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上正常工作。

- shry

Answer 2

包含 'globaltoc.html' 的缺点在于它无法显示你正在查看的页面的全局和本地目录。

看起来其他人也对此限制感到恼怒，因此随后开发了一个扩展程序，支持侧边栏中的 完整目录。请查看: https://pypi.python.org/pypi/sphinxcontrib-fulltoc

- dbailey

---

这很好用！但是我必须先运行 pip install --upgrade setuptools，否则它会因为一个奇怪的错误而无法安装：AttributeError: '_NamespacePath' object has no attribute 'sort'。 - alexanderlukanin13

当readthedocs尝试安装此内容时，我目前收到了这个错误报告。 - Chris

@Chris 我怀疑 https://github.com/sphinx-contrib/fulltoc/issues/14 是这个问题的原因，我会尽快调查。 - dbailey

Answer 3

默认的Sphinx侧边栏“导航”部分不会显示任何内容，直到您在.rst文件中将要扫描的章节标题文件的名称添加到toctree::指示中。例如，如果您希望在导航窗格中显示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自动生成的模板开始项目 (截至撰写本文)，该模板将你的.rst文件用空的toctree填充。

- SigmaX

Answer 4

不要忘记在代码中使用:hidden:关键字。

.. toctree::
    :maxdepth: 1
    :hidden:

    index
    docs/specification
    docs/ux
    docs/database
    docs/techstack
    docs/api
    docs/specialFunctionalities
    enter code here

- Mohamed Aymn