一、sphinx-doc 中文搜索优化
- 升级
sphinx至最新版本pip install Sphinx==1.8.1 - 在
config.py中添加如下参数
# Language to be used for generating the HTML full-text search index.
html_search_language = 'zh'
# A dictionary with options for the search language support, empty by default.
html_search_options = {'dict': 'user_dict'}
- 在
config.py的同级目录创建user_dict文件，user_dict格式如下：
# 格式说明, 一个词占一行；每一行分三部分：词语、词频（可省略）、词性（可省略），用空格隔开，顺序不可颠倒。
# 详见 https://github.com/fxsjy/jieba
创新办 3 i
云计算 5
凱特琳 nz
台中
- 使用命令编译文档
make html
- 上传文件
将编译好的_xxx/html/searchindex.js文件上传到站点即可
二、自动生成 PDF
1. 环境准备
由于 sphinx 编译 PDF 的过程中使用了 latexpdf 组件，该组件在windows/macOS/Linux上安装方式和使用方式均有不同，建议直接使用 Docker 环境来编译。
方法一：使用 Dockerfile 自主编译 image
创建Dockerfile, 内容如下：
FROM python:3.6
RUN apt-get update && \
apt-get install -y git mercurial texlive-full xzdec && \
apt-get clean && \
rm -rf /var/lib/apt/lists/* && \
pip install sphinx sphinx-rtd-theme PyYAML
编译 Dockerfile：
docker build -t sphinx-pdf-zh .
方法二：使用 Dockerhub 上编译好的镜像
如遇网络问题，请自行解决。
docker pull iccccing/sphinx-pdf-zh
2. 参数设置
为了满足中文编码的支持，需要在config.py中设置如下参数：
# -- Options for LaTeX output ---------------------------------------------
# 以下为LaTeX语法，可以配置编码格式、字体等，详解请自行百度
latex_elements = {
'preamble': '''
\\hypersetup{unicode=true}
\\usepackage{CJKutf8}
\\AtBeginDocument{\\begin{CJK}{UTF8}{gbsn}}
\\AtEndDocument{\\end{CJK}}
'''
}
3. 运行容器
运行容器，并挂载文档到容器：
# 命令中/my/doc/path 为文档所在路径，请注意修改
docker run -it -v /my/doc/path:/my/doc/path --name my-sphinx iccccing/sphinx-pdf-zh /bin/bash
4. 开始编译
进入容器：
docker exec -it my-sphinx bash
开始编译：
# 命令中/my/doc/path 为文档所在路径，请注意修改
cd /my/doc/path
make latexpdf
5. 查看文件
进入编译结果目录_xxx/latex可以看到xxx.pdf文件
