sphinx生成中文的PDF

September 01, 2014 / Unix LIKE / apacal / 1729 CLICK / 0 comment

Sphinx 是一种工具，它允许开发人员以纯文本格式编写文档，以便采用满足不同需求的格式轻松生成输出。这在使用 Version Control System 追踪变更时非常有用。纯文本文档对不同系统之间的协作者也非常有用。纯文本是当前可以采用的最便捷的格式之一。  虽然 Sphinx 是用 Python 编写的，并且最初是为 Python 语言文档而创建，但它并不一定是以语言为中心，在某些情况下，甚至不是以程序员为中心。Sphinx 有许多用处，比如可以用它来编写整本书！ 突出显示  默认情况下，Sphinx 会为 Python 突出显示代码，但它还允许定义其他编程语言，比如 C 和 Ruby。  可以将 Sphinx 想像成为一种文档框架：它会抽象化比较单调的部分，并提供自动函数来解决一些常见问题，比如突出显示标题索引和特殊代码（在显示代码示例时），以及突出显示适当的语法。 
　　sphinx可以利用LaTeX将rST源文件转换成PDF文件，但是官方的是不支持中文的，因而必须要对其进行修改。对于生成pdf的中文，我们责任选择比较好的xelatex

相关(类似)的名词太多了，想分清真不容易

<table>
	<tbody>
		<tr>
			<td colspan="1" rowspan="6" style="text-align:center">
			引擎
			</td>
			<td>
			(Knuth)TeX
			</td>
			<td>
			真正的(原始的)TeX
			</td>
		</tr>
		<tr>
			<td>
			ε-TeX
			</td>
			<td>
			相对于原始的TeX它提供了一种扩展模式
			</td>
		</tr>
		<tr>
			<td>
			pdfTeX
			</td>
			<td>
			它从tex文件不通过dvi文件直接生成pdf文件（开发者已经转向LuaTeX）
			</td>
		</tr>
		<tr>
			<td>
			XeTeX
			</td>
			<td>
			相对于原始的TeX，主要增加了Unicode和 OpenType 的支持
			</td>
		</tr>
		<tr>
			<td>
			LuaTeX
			</td>
			<td>
			它使用Lua作为扩展语言，对于LaTeX支持尚不完善？
			</td>
		</tr>
		<tr>
			<td>
			...
			</td>
			<td> </td>
		</tr>
		<tr>
			<td colspan="1" rowspan="5" style="text-align:center">
			宏集
			</td>
			<td>
			plain TeX
			</td>
			<td>
			最古老的TeX宏集，提供了一些最基本的命令
			</td>
		</tr>
		<tr>
			<td>
			AMSTeX
			</td>
			<td>
			是美国数学会提供的一个TeX宏集，它添加了许多数学符号和数学字体
			</td>
		</tr>
		<tr>
			<td>
			LaTeX
			</td>
			<td>
			相对于PlainTeX，它使得科技文档的排版更加直观和方便
			</td>
		</tr>
		<tr>
			<td>
			ConTeXt
			</td>
			<td>
			和LaTeX 相比，它更加灵活和自由
			</td>
		</tr>
		<tr>
			<td>
			...
			</td>
			<td> </td>
		</tr>
		<tr>
			<td colspan="1" rowspan="6" style="text-align:center">
			发行版
			</td>
			<td>
			TeX Live
			</td>
			<td>
			国际TeX用户组织TUG开发,支持不同的操作系统
			</td>
		</tr>
		<tr>
			<td>
			MiKTeX
			</td>
			<td>
			Windows 下广泛使用的一个TeX发行版
			</td>
		</tr>
		<tr>
			<td>
			ConTeXt Minimals
			</td>
			<td>
			它包含了最新版本的 ConTeXt
			</td>
		</tr>
		<tr>
			<td>
			teTeX
			</td>
			<td>
			一个Unix下的TeX发行版，现在已经停止更新且并入TeXLive
			</td>
		</tr>
		<tr>
			<td>
			fpTeX
			</td>
			<td>
			一个Windows的TeX发行版，已不再更新
			</td>
		</tr>
		<tr>
			<td>
			...
			</td>
			<td> </td>
		</tr>
	</tbody>
</table>

真够乱的，还好，我们只关注一部分：

<h3>LaTeX</h3>

原始的TeX已经有了一组宏集，也就是Knuth所写的著名的Plain TeX(原始的TeX和Plain Tex都是《The TeXbook 》一书中介绍的内容)。

但是这些命令仍然很底层，不够方便、直观，于是Leslie Lamport写了另一组宏，称为LaTeX，主要是它版本配置和文中内容适度分开处理。

LaTeX 2ε是自1993年以来LaTeX的一个稳定版本，是目前大部分LaTeX书籍的主体内容。

ctex宏包提供了一个统一的中文LaTeX文档框架,底层支持CCT、CJK和xeCJK三种中文LaTeX系统。

<ul>
	<li>CCT 非常不推荐了</li>
	<li>CJK 这个？应该在windows下工作还很不错</li>
	<li>xeCJK 比较推荐</li>
</ul>

ctex宏包提供了编写中文LaTeX文档常用的一些宏定义和命令。

主要文件包括ctexart.cls、ctexrep.cls、ctexbook.cls 和 ctex.sty、ctexcap.sty。

先来看一下sphinx生成pdf的流程： 
　　当执行<code>make latexpdf</code>时，会首先执行<code>sphinx-build</code>生成tex源文件，然后调用<code>_build/latex</code>目录下的makefile文件，利用pdflatex引擎将tex文件转换为PDF。 <code>_build/latex</code>下的Makefile文件是<code>sphinx/texinputs/Makefile</code>的直接拷贝。因而需要修改<code>sphinx/texinputs/Makefile</code>，将其中的pdflatex修改成xelatex。 
 
　　建议使用编译源码的方式安装sphinx，<a href="http://sphinx-doc.org/install.html">http://sphinx-doc.org/install.html</a>，可以方便找到Makefile，latex.py等文件。 
我们假定你下载的sphinx源码在/opt/sphinx下，后面说的<code>sphinx/texinputs/Makefile</code>等是在sphinx下的

<ul>
	<li>
	修改Makefile文件
	</li>
</ul>

修改<code>sphinx/texinputs/Makefile</code>，将其中的pdflatex修改成xelatex。

<pre>
 (apacal)-(jobs:1)-(/opt/sphinx)
(! 2049)-> pwd
/opt/sphinx

(apacal)-(jobs:1)-(/opt/sphinx)
(! 2050)-> vim sphinx/texinputs/Makefile

# Makefile for Sphinx LaTeX output

ALLDOCS = $(basename $(wildcard *.tex))
ALLPDF = $(addsuffix .pdf,$(ALLDOCS))
ALLDVI = $(addsuffix .dvi,$(ALLDOCS))

# Prefix for archive names
ARCHIVEPRREFIX =
# Additional LaTeX options
LATEXOPTS =

LATEX = latex
PDFLATEX = xelatex
MAKEINDEX = makeindex

</pre>

<ul>
	<li>
	修改latex.py

如果make latexpdf时出现下面错误，则是说明没有修改latex.py文件

<pre>
 ! Undefined control sequence.
\GenericError ...
 #4 \errhelp \@err@ ...
l.2856 }</pre>
	修改<code>sphinx/writers/latex.py</code>，在231行左右加入语句对中文做特殊处理：

<pre>
 if builder.config.language == 'zh_CN':
 self.elements['babel'] = ''
 self.elements['inputenc'] = ''
 self.elements['utf8extra'] = ''</pre>
	</li>
	<li>
	编译安装sphinx
	</li>
</ul>

对sphinx源代码的修改就好了，编译安装sphinx

<ul>
	<li>修改conf.py</li>
</ul>

编译好后， 使用sphinx-quickstart 建立一个新的sphinx项目，直接make latexpdf之后不会报错，但是中文部分完全没有显示，这是因为缺乏中文所需要的字体设置。修改conf.py中的latex_elements参数，和加上如下:（conf.py是你sphinx项目下的配置文件）

<pre>
 (apacal)-(jobs:0)-(~/git/language/sphinx/example)
(! 2009)-> pwd
/home/apacal/git/language/sphinx/example

(apacal)-(jobs:0)-(~/git/language/sphinx/example)
(! 2010)-> ls
_build  conf.py  example.rst  index.rst  make.bat  Makefile  _static  _templates

(apacal)-(jobs:0)-(~/git/language/sphinx/example)
(! 2011)-> vim conf.py

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': r'''
    \usepackage{xecjk}
    \setcjkmainfont{wenquanyi micro hei}
    \xetexlinebreaklocale "zh"
    \xetexlinebreakskip = 0pt plus 1pt
''',
# the paper size ('letterpaper' or 'a4paper').
#'papersize': 'letterpaper',

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

# additional stuff for the latex preamble.
#'preamble': '',
}
</pre>

<pre>
 # The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
language = 'zh_CN'
</pre>

现在sphinx可以生成中文pdf，包括中文目录。

LATEX

使用vundle来管理VIM插件

daemontools使用

Your email address will not be published. Required fields are marked *, You could login

User Name *

User Email *

Website

sphinx生成中文的PDF

Previous post

使用vundle来管理VIM插件

Next post

daemontools使用

Leave a Reply