在Mac上使用Sphinx产生文档并生成中文PDF文档

什么是sphinx ? Sphinx is a tool that makes it easy to create intelligent and beautiful documentation, written by Georg Brandl and licensed under the BSD license. It was originally created for the new Python documentation, and it has excell

什么是sphinx ?

Sphinx is a tool that makes it easy to create intelligent and beautiful documentation, written by Georg Brandl and licensed under the BSD license.

It was originally created for the new Python documentation, and it has excellent facilities for the documentation of Python projects, but C/C++ is already supported as well, and it is planned to add special support for other languages as well.

安装Sphinx

<code>pip install sphinx
</code>

使用Sphinx创建文档工程

<code>mkdir docs
sphinx-quickstart
</code>

sphinx-quickstart会问你一连串的问题，完成之后会创建基本的文档工程文件。其中配置文件为conf.py。

Sphinx支持输出html和pdf文档。输出html很简单：

<code>make html
</code>

它会把生成的html文档存放在_build/html目录下。

要生成pdf的话，需要先安装Latex，推荐使用MacTex，它的安装包约有2GB，安装需要4GB的空间。

如果文档是纯英文文档，要生成pdf很简单，只需要执行下面的命令即可：

<code>make latexpdf
</code>

它会把生成的html文档存放在_build/pdf目录下。

如果在文档中有中文，使用这种方法产生pdf的话pdflatex会提示错误。

要解决这个问题，需要修改conf.py中的latex配置，在生成的latex文件中添加对中文的支持。 在conf.py中找到latex_elements并修改为如下：

<code>latex_elements = {
# The paper size ('letterpaper' or 'a4paper').
'papersize': 'a4paper',
# The font size ('10pt', '11pt' or '12pt').
'pointsize': '12pt',
'label': '\\usepackage[english]{babel}',
# Additional stuff for the LaTeX preamble.
'preamble': '''
\usepackage{xeCJK}
\usepackage{indentfirst}
\setlength{\parindent}{2em}
\setCJKmainfont[BoldFont=SimHei, ItalicFont=STKaiti]{SimSun}
\setCJKmonofont[Scale=0.9]{STKaiti}
\setCJKfamilyfont{song}[BoldFont=SimSun]{SimSun}
\setCJKfamilyfont{sf}[BoldFont=SimSun]{SimSun}
\XeTeXlinebreaklocale "zh"
\XeTeXlinebreakskip = 0pt plus 1pt
'''
}
</code>

其中字体的设置是需要根据你系统中可用的中文字体来确定， 可以使用fc-list命令来查看系统支持的中文字体：

<code>fc-list :lang=zh
</code>

在获取到系统支持的中文字体后，选择喜欢的字体即可。

要在latex中支持中文，需要使用xelatex命令来产生pdf文档。

<code>make latex
cd _build/latex
xelatex *.tex
</code>

参考

• http://sphinx-doc.org/tutorial.html
• http://sphinx-doc.org/rest.html
• http://people.ee.ethz.ch/~creller/web/tricks/reST.html
• http://kkdevs.tumblr.com/post/38275843739/sphinx-latex-pdf
• http://www.tug.org/mactex/

原文地址：在Mac上使用Sphinx产生文档并生成中文PDF文档, 感谢原作者分享。