Python-Sphinx 中 Toctree 的多个级别

Question

我正在尝试使用 sphinx 来记录多个“级别”的文档，例如：

• 接口参考
• 手动的
• 教程
• 等等。

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

我一直在试图弄清楚如何让它在 Sphinx 中工作而不入侵它，但到目前为止还想不出办法。 文件夹结构已经反映了不同的部分（即所有“手册”文档都存储在 _source/manual 下），我已经尝试在每个目录中放置单独的索引文件，但似乎 toctree 功能只查看主索引文件。

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

谁能告诉我如何使用 Sphinx 添加这样的 ToC？

谢谢

Answer 1

（这个回复可能有点晚了）我有类似的情况，同一目录树中包含三个部分：

• 硬件
• 软件
• 教程

我试图实现相同的目标，即从我的侧边栏菜单中隐藏不属于当前 toctree-l1 的所有内容。 知道 Sphinx 添加了 CSS 类“current”，我想出了：

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

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

我的菜单的屏幕截图仅显示一个部分下方的内容：

Answer 2

似乎子目录中文档中的.. toctree::以该子目录为根（参见例如https://docs.python.org/2/_sources/howto/index.txt ）。 对于上层 TOC， :maxdepth:限制包含较低层。

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