reStructuredText Sphinx HTML中文搜索解决方案

默认情况下，reStructuredText Sphinx生成的HTML站点对中文搜索支持非常有限，基本上那个搜索框就是个摆设而已。Google一下，发现早就有高手给出了中文分词解决方案，只不过那个方案没有step-by-step的介绍，对新手而言可能不太容易理解，这里我就详细说明下吧。

首先要感谢《用Sphinx写书》这个教程的作者张若愚（这位大神还写过一本《Python科学计算》，貌似评价不错），是他把开源中文分词工具包smallseg引入到reStructuredText Sphinx中的，没有他写的这个教程也就不会有我的这篇日志啦。

按照《用Sphinx写书》的介绍，Sphinx HTML中文分词需要用到smallseg，至于具体如何配置，则没有介绍……好消息是，大神慷慨地放出了自己搭建的Sphinx写作环境（还不加版权限制），所以我们可以下载回来研究下（原教程的下载链接已经失效，不过作者在这里也提供了下载，请自备“梯子”访问之）。

经观摩一番之后，个人总结得出，为reStructuredText Sphinx生成的HTML添加中文搜索功能，只需要配置如下（Windows环境，Sphinx v1.1.3）：

1）在你的Sphinx项目根目录下创建一个exts文件夹

2）将《用Sphinx写书》提供的写作环境包解压，把以下文件复制到步骤1）创建的文件夹中：

chinese_search.py
chinese_search.pyc
main.dic
smallseg.py
smallseg.pyc
suffix.dic
zh.py
zh.pyc

3）修改conf.py文件

3.1）

添加两行配置

_exts = “../exts”

sys.path.append(os.path.abspath(_exts))

需要说明的是，”../exts”是一个相对路径，其中“../”表示当前配置文件conf.py的上一级目录，所以”../exts”的意思就是与conf.py所在目录同一级别的另一个目录exts，这个路径是可以根据需要自行修改的。

3.2）

为扩展配置参数 extensions = [ ] 添加 ‘chinese_search’

4）修改语言配置参数 language 为 ‘zh_CN’

改完以上配置后，运行make html，检验一下效果如何。

上面说得好像有点抽象了，好吧，上一张目录结构示意图帮助大家理解：
前面描述的都是针对简体中文的情景，实际上在技术文档写作中，繁体中文版本经常也是标配的需求。那咋办呢？繁体版也直接套用上面这套操作步骤？肯定不行，因为我试过了……经研究，只需简单修改一下配置，繁体中文版就能实现类似效果：

1）用文本编辑器打开chinese_search.py，将”zh_CN”改为”zh_TW”并保存
2）修改conf.py语言配置参数 language 为 ‘zh_TW’

其实我很好奇，smallseg的词库都是简体的，为何也能对繁体中文进行分词处理呢……对了，既然有繁体中文版的需求，自然就会涉及到简繁转换的问题，可以参考我之前写过的《开源简繁转换工具OpenCC在技术文档写作中的批处理应用》（如果你用Word来对Sphinx源文档进行简繁转化的话，格式会乱掉的，所以还是推荐使用OpenCC）。

Ps: 如果你没办法爬#过%墙去下载《用Sphinx写书》的写作环境包，请留言说明，我可以用邮箱给你发一份。之所以不在这篇日志里自行提供下载链接，主要是为了对原作者表示尊重。