Mac上使用Sphinx + latex输出中文PDF

很早以前有篇文章介绍了如何用sphinx写文档。以前没有使用Sphinx写过中文文档，所以也没有碰到什么问题。最近写了一份中文文档，由于Sphinx对中文的支持不太友好，转中文PDF的时候遇到不少坑，网上做了很多搜索，很多尝试后终于搞定。这里写篇文章记录下，希望对大家有帮助。

Mac上安装Sphinx

easy_install sphinx

创建Sphinx项目

sphinx-quickstart

Sphinx直接编译输出PDF

使用sphinx输出pdf文档需要安装额外的插件。可以使用rst2pdf，它是一个python开发的插件，安装和使用都比较方便。

安装rst2pdf

easy_install rst2pdf

在conf.py中配置rst2pdf

1. 添加rst2pdf扩展

   extensions = ['rst2pdf.pdfbuilder']
   

2. 增加pdf文档的变量

   # index - master document
   # rst2pdf - name of the generated pdf
   # Sample rst2pdf doc - title of the pdf
   # Your Name - author name in the pdf
   pdf_documents = [('index', u'rst2pdf', u'Sample rst2pdf doc', u'Your Name'),]
   

编译pdf文档

make pdf

由于sphinx不支持中文，要通过rst2pdf输出包含中文的PDF文档有点麻烦，需要通过更改设置能够支持中文的字体的方式实现。这里不采用这种方式，使用latex来实现输出中文文档。

通过Latex输出中文PDF

安装latex可以选择完整安装，和安装latex-base版本。完整安装仅安装包就有约2.7G，latex-base是一个基础包，安装包100M左右，安装需要400M不到的空间。我们目前仅需要通过latex输出PDF文档，所以不需要安装完整安装。使用latex-base就可以了。但是latex-base安装后，不能直接使用，还需要一些额外操作才能正常支持中文格式。

Latex在Mac OS中叫MacTex.

安装BasicTex

1. 从官网下载BaisicTex安装包，下载链接：http://tug.org/cgi-bin/mactex-download/BasicTeX.pkg

2. 下载完成后，直接双击安装即可。

   坑：安装完成后，相应工具集的路径并不会被添加到环境变量中，所以这时直接执行相应工具，或配置编译，会报找不到相应工具的错误。

3. 添加工具路径到环境变量$PATH中。工具路径一般在/usr/local/texlive/2016basic/bin/universal-darwin/ (注： ”2016basic“是我安装的版本，如果你安装的版本不同这个文件的名字可能不同。）

   1）修改.bash_profile, 添加如下行：

   export PATH=$PATH:/usr/local/texlive/2016basic/bin/universal-darwin/
   

   2）使修改生效

   source ~/.bash_profile
   

安装一些额外的tex包

安装完成后，如果你直接开始配置sphinx的配置文件，编译pdf，你可能会遇到很多错误。这是因为我们只是安装的了basic的latex包，要支持中文pdf的输出，还需要一些额外的包。

MacTex提供了一个叫tlmgr的包管理工具，我们可以直接通过这个工具安装需要的包。BasicTex安装后，这个工具也被安装到了前面提到的工具路径中。因为我们已经添加了路径到环境变量中，所以可以直接执行这个命令了。

1. 更新tlmgr

   sudo tlmgr update --self
   

2. 安装相应的工具

   需要安装的工具有： titlesec、framed、threeparttable、wrapfig、multirow、enumitem、bbding、titling、tabu、mdframed、tcolorbox、textpos、import、varwidth、needspace、tocloft、ntheorem、environ、trimspaces、collection-fontsrecommended、capt-of、eqparbox、cjk

   sudo tlmgr install titlesec framed threeparttable wrapfig multirow enumitem bbding titling tabu mdframed tcolorbox textpos import varwidth needspace tocloft ntheorem environ trimspaces collection-fontsrecommended capt-of eqparbox cjk
   

修改配置文件 config.py

在latex_elements = {...}中添加如下内容：

'papersize': 'a4paper',
'preamble': '''
\hypersetup{unicode=true}
\usepackage{CJKutf8}
\DeclareUnicodeCharacter{00A0}{\\nobreakspace}
\DeclareUnicodeCharacter{2203}{\ensuremath{\exists}}
\DeclareUnicodeCharacter{2286}{\ensuremath{\subseteq}}
\DeclareUnicodeCharacter{2713}{x}
\DeclareUnicodeCharacter{27FA}{\ensuremath{\Longleftrightarrow}}
\DeclareUnicodeCharacter{221A}{\ensuremath{\sqrt{}}}
\DeclareUnicodeCharacter{221B}{\ensuremath{\sqrt[3]{}}}
\DeclareUnicodeCharacter{2295}{\ensuremath{\oplus}}
\DeclareUnicodeCharacter{2297}{\ensuremath{\otimes}}
\\begin{CJK}{UTF8}{gbsn}
\AtEndDocument{\end{CJK}}
'''

注：\n和\b都是Python中的转义字符，所以配置中的\nobreakspace和\begin都需要使用两个\\。

编译

一切就绪后，执行make latexpdf就直接可以在build/latex目录下生产pdf文档。

注：编译过程中可能还会遇到报! Undefined control sequence.的错误，博主直接回车忽略了此错误，仍然能正确生成中文PDF，所以没有对此错误做深入研究。