Python-Sphinx中Toctree的多个级别

Posted 2021-04-29

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

• Api参考
• 手册
• 教程
• 等等。

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

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

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

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

谢谢

答案

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

• 硬件
• 软件
• 教程

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

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

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

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

另一答案

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

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