Python-Sphinx中的多级Toctree

Question

我正在尝试使用 Sphinx 来记录多个“层级”的文档，比如：

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

我的想法是，目录会在侧边栏显示，跟你所在的部分相关。所以当你在主索引时，只显示上面提到的部分。当你进入“手册”时，它会显示一个特定于该部分的不同目录，并且有一个返回主目录的方式。

我一直在尝试找出如何在 Sphinx 中实现这个功能，而不是通过一些黑科技来搞定，但到目前为止还没找到合适的方法。文件夹结构已经反映了不同的部分（也就是说，所有的“手册”文档都存放在 _source/manual 目录下），我也尝试在每个目录中放置单独的索引文件，但似乎目录树的功能只关注主索引文件。

我使用的是“readthedocs”主题，我正在查看的代码具体在 这个链接 上。

有没有人能告诉我如何在 Sphinx 中添加这样的目录？

谢谢

Answer 1

看起来在一个子目录里的文档中，使用 .. toctree:: 的时候，它的根目录是这个子目录（比如你可以看看 https://docs.python.org/2/_sources/howto/index.txt）。对于上层的目录结构，:maxdepth: 这个参数可以限制显示更低层级的内容。

你可以通过制作一个相应的模板，把它放到侧边栏中，并将其添加到 html_sidebars 这个构建参数里。 更新：这个方法不管用；在侧边栏模板中，目录结构总是从顶部开始。

Answer 2

(可能这个回复有点晚了) 我遇到了类似的情况，有三个部分在同一个目录树里：

• 硬件
• 软件
• 教程

我想做的就是在侧边菜单中隐藏所有不属于当前目录树一级的内容。知道Sphinx会添加一个叫'current'的CSS类，所以我想到了：

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

这不是最完美的解决方案，但由于Sphinx只能处理一个主根目录来生成文档，从这个主目录开始，它会创建整个目录树。如果你只需要在侧边菜单中使用，CSS应该能帮到你。

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