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,检验一下效果如何。

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

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

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

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

“reStructuredText Sphinx HTML中文搜索解决方案”的2个回复

  1. 我使用的是Python 3.4 。 安装的是 jiaba 分词工具。因为这个工具一直在更新 。 安装过程如下sphinx 安装笔记===============首先安装好Python—————-我的环境是win7-64位,安装的是Python 3.4.2安装Python的sphinx插件———————-在Python目录下Scripts目录下运行“pip3.4.exe install sphinx”命令。 就可以安装sphinx扩展包了。 :: pip3.4.exe install sphinx解决reStructuredText Sphinx HTML中文搜索—————————————-安装jieba3k (因为我的是Python3.4) :: C:Python34Scripts>pip3.4.exe install jieba3k在https://github.com/bosbyj/sphinx.search.zh_CN下载zh_CN.py :: https://github.com/bosbyj/sphinx.search.zh_CN拷贝到C:\Python34\Lib\site-packages\sphinx\search 目录下修改这个目录下的_init_.py文件,找到 :: from sphinx.search import en, ja languages = { ‘en’: en.SearchEnglish, ‘ja’: ja.SearchJapanese, }修改为 :: from sphinx.search import en, ja, zh_CN languages = { ‘en’: en.SearchEnglish, ‘ja’: ja.SearchJapanese, ‘zh_CN’: zh_CN.SearchChinese }在 sphinx 工程的 conf.py 中修改 :: language = ‘zh_CN’ html_search_language = `zh_CN` 然后就可以 make html 了为reStructuredText Sphinx扩展侧边栏目录—————————————在Python目录下Scripts目录下运行“easy_install-3.4.exe sphinxcontrib-fulltoc” 就可以安装这个扩展包了修改Sphinx项目配置文档conf.py 。为扩展参数 extensions = [ ] 添加值 ‘sphinxcontrib.fulltoc’ 记得后面加逗号重新执行一次make html

发表评论

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