用sphinxcontrib-fulltoc为reStructuredText Sphinx扩展侧边栏目录

使用reStructuredText Sphinx生成的HTML站点,在首页和每一页的侧边栏都会显示导航目录。问题是,默认的目录形式还不够高效,仍有可改进的空间。

如下图所示,默认情况下,当前页面只会显示该页面包含的章节标题链接,以及前后各一个章节的标题链接。如果你想要看其他章节的内容,只能点击首页链接,回到首页去查找完整的章节目录。
without-sphinxcontrib-fulltoc
要是能把侧边栏的导航目录扩展一下,包含所有的章节标题,那该多方便呀!话说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

实际效果图如下:
with-sphinxcontrib-fulltoc

Ps: 公司同事某Pan对于本文有所贡献,其指出了Sphinx默认侧边栏目录的不足。

“用sphinxcontrib-fulltoc为reStructuredText Sphinx扩展侧边栏目录”的5个回复

  1. 你好,我是中文win7 64位 环境安装了Python 3.42 。 用easy_install 安装了sphinx 1.3b2用easy_install 安装了sphinxcontrib-fulltoc 1.1也修改了conf.py文件但make html 的时候报如下错误Extension error:Could not import extension sphinxcontrib (exception: No module named ‘sphinxcontrib’)望不吝赐教我的QQ:36594475

  2. 我使用的是C:Python34Scripts>easy_install-3.4.exe sphinxcontrib-fulltoc 安装的。有这个提示 Processing sphinxcontrib_fulltoc-1.1-py3.4.egg 这个版本应该是支持Python 3.4的

发表评论

电子邮件地址不会被公开。 必填项已用*标注