Python-Sphinx 中的多级 Toctree

Question

我试图用Sphinx记录多个“层次”文档，例如：

• API参考
• 手册
• 教程
• 等等

这个想法是在侧边栏中相对于你所在的部分显示目录。因此，当你在主索引上时，它只显示上述部分。当您进入例如“手册”时，它会显示特定于该部分的不同目录，以及返回主目录的方法。

我一直在尝试找出如何在Sphinx中获取此功能，而不需要修改代码，但到目前为止仍然无法完全理解。文件夹结构已经反映了不同的部分（即所有“手册”文档都存储在_source/manual下），并且我已经尝试在每个目录中放置单独的索引文件，但似乎toctree功能仅查看主索引文件。

我正在使用“readthedocs”主题，我特别查看的代码是https://github.com/snide/sphinx_rtd_theme/blob/master/sphinx_rtd_theme/layout.html#L93

有人可以告诉我如何使用Sphinx添加此类目录吗？

谢谢

- Naatan

Answer 1

（也许有点晚了）我有一个类似的情况，三个部分包含在同一个TOC树中：

• 硬件
• 软件
• 教程

我试图达到相同的效果，即从我的侧边栏菜单中隐藏与当前toctree-l1无关的所有内容。知道Sphinx添加CSS类“current”，我想到了：

#sidebar li.toctree-l1:not(.current){
  display: none;
} 

这不是最好的解决方案，但由于Sphinx只能处理一个主根文档，并从该文档创建整个TOC Tree，如果您只需要侧边栏菜单，CSS应该适合您。

我的菜单截图只显示一个部分下面的内容：

- Begoña Álvarez de la Cruz

Answer 2

看起来在子目录中的文档中的.. toctree::是以该子目录为根目录的（例如请参见https://docs.python.org/2/_sources/howto/index.txt）。对于上层目录，:maxdepth:限制了包含较低级别的内容。

这可以通过创建相应的模板并将其添加到html_sidebars构建参数中来放置在侧边栏中。更新：不起作用；在侧边栏模板中，TOC始终以顶部为根目录。

- ivan_pozdeev