5. 生成PDF¶

本文更新于 2018.05.09

参考：

http://www.tuicool.com/articles/nAJJVb
http://www.tuicool.com/articles/bEvYv2V
http://linux-wiki.cn/wiki/zh-hans/LaTeX中文排版（使用XeTeX）
http://brianhsu.moe/blog/2012-03-23-SphinxXeTex.html

生成PDF的前提是安装了texlive:

sudo apt-get install texlive-full

我们一般是生成带中文的pdf，会比较复杂，主要有两种方法。

5.1. 方法一：使用xeTex(推荐)¶

xeTex支持UTF8编码的源文件，并且可以用系统中已有的中文字体来生成pdf。

安装xetex软件包:

sudo apt-get install texlive-xetex

使用fc-list命令可以查看系统当前可用的中文字体:

fc-list :lang=zh

如果觉得已有字体不够用，可以从windows系统拷贝字体: http://linux-wiki.cn/wiki/zh-hans/LaTeX中文排版（使用XeTeX）

接着配置conf.py，把latex_elements中premble改成:

# Additional stuff for the LaTeX preamble.
'preamble': '''
\\hypersetup{unicode=true}
\\usepackage{xeCJK}
\\usepackage{hyperref}
\\setCJKmainfont{NSimSun}
\\setCJKmonofont{NSimSun}
''',

这里是用了新宋体。

注解

如果系统中没有相应的字体, 比如在macOS上, 可以下载或从windows系统拷贝相应的字体(一般是ttf或ttc文件), 然后双击它根据提示进行安装)

然后，首先在文档源文件主目录运行 make latex 生成latex文件，如xxx.tex，打开xxx.tex，将含有inputenc的行注释掉，因为inputenc组件与xeTex冲突:

%\usepackage[utf8]{inputenc}

最后再用 xelatex xxx.tex 编译生成的latex文件两次即可。编译两次的原因是第1次不会生成目录和索引。

5.2. 方法二: 使用CJKutf8包 (默认)¶

安装东亚语言包和字体包(texlive-lang-cjk, texlive-fonts-recommands之类）:

sudo apt-get install texlive-langextra texlive-langcjk

配置conf.py，在latex_elements中加入:

latex_elements = {
# The paper size ('letterpaper' or 'a4paper').
#'papersize': 'letterpaper',

# The font size ('10pt', '11pt' or '12pt').
#'pointsize': '10pt',

# Additional stuff for the LaTeX preamble.
'preamble': '''
\\hypersetup{unicode=true}
\\usepackage{CJKutf8}
\\AtBeginDocument{\\begin{CJK}{UTF8}{gbsn}}
\\AtEndDocument{\\end{CJK}}
''',

最后运行 make latexpdf 即可。

这种方法经常会在编译pdf的过程中出一些莫名其妙的错误，而且本人不太latex，很难排查到底是哪里出了错误。

5.3. 终极解决办法¶

不管采用上面哪种方法, 有时候还是会出现pdf生成错误, 而错误信息几乎没有参考价值, 根本不知道哪个rst文件及哪一行出错了.

通过使用xeTex, 并使用自己编译生成的sphinx, 目前看来可以完美解决这些问题, 因此称为 终极解决办法 . 参考链接: http://apacal.cn/article/76.html

确认conf.py里的语言设置为中文:
```
language = 'zh_CN'
```
确保安装了xeTex
下载sphinx源码包, 目前(2017.07.03)最好用1.5.6, 最新版本有bug, 地址 https://github.com/sphinx-doc/sphinx/archive/v1.5.6.tar.gz
解压源码包, 假设为/home/zzq/sphinx-1.5.6, 下文都基于此目录讨论
修改 sphinx/texinputs/Makefile_t , 将PDFLATEX修改为xelatex:
```
PDFLATEX = xelatex
```

修改 sphinx/writers/latex.py , 在第442行左右, 加入以下代码:

# zzq
if builder.config.language == 'zh_CN':
    self.elements['babel'] = ''
    self.elements['inputenc'] = ''
    self.elements['utf8extra'] = ''

加入的位置在以下代码之前:

# pTeX (Japanese TeX) for support
if builder.config.language == 'ja':

回到sphinx源码主目录, 执行 sudo pip install . 安装修改后的sphinx, 在安装前请确保旧版本已被删除.
到你的reST文档主目录(conf.py在的目录), 运行 make latexpdf 即可生成pdf.