使用reStructuredText Sphinx生成的HTML站点，在首页和每一页的侧边栏都会显示导航目录。问题是，默认的目录形式还不够高效，仍有可改进的空间。
如下图所示，默认情况下，当前页面只会显示该页面包含的章节标题链接，以及前后各一个章节的标题链接。如果你想要看其他章节的内容，只能点击首页链接，回到首页去查找完整的章节目录。
要是能把侧边栏的导航目录扩展一下，包含所有的章节标题，那该多方便呀！话说Sphinx虽然自身不具备这个功能，但其强悍之处就在于支持自定义扩展。网上有人做出了一个叫做sphinxcontrib-fulltoc的扩展程序，能够在侧边栏显示所有的一级标题，浏览效率顿时就提高了，有没有！
英文版的官方教程在这里，本文只是用地球人能够看懂的中文描述一遍我的做法（以Windows平台为例）：
1）在此页面下载sphinxcontrib-fulltoc 1.0扩展程序包
2）将sphinxcontrib-fulltoc扩展程序包解压，用CD命令切换到其根目录，在命令行窗口中执行以下命令：
python setup.py install
3）修改Sphinx项目配置文档conf.py
为扩展参数 extensions = [ ] 添加值 'sphinxcontrib.fulltoc'
4）重新执行一次make html
实际效果图如下：
Ps: 公司同事某Pan对于本文有所贡献，其指出了Sphinx默认侧边栏目录的不足。
发表回复