Sphinx 中文搜索优化和中文pdf生成

一、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文件