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 基础知识 名词 相关(类似)的名词太多了,想分清真不容易 引擎 (Knuth)TeX 真正的(原始的)TeX ε-TeX 相对于原始的TeX它提供了一种扩展模式 pdfTeX 它从tex文件不通过dvi文件直接生成pdf文件(开发者已经转向LuaTeX) XeTeX 相对于原始的TeX,主要增加了Unicode和 OpenType 的支持 LuaTeX 它使用Lua作为扩展语言,对于LaTeX支持尚不完善? ... 宏集 plain TeX 最古老的TeX宏集,提供了一些最基本的命令 AMSTeX 是美国数学会提供的一个TeX宏集,它添加了许多数学符号和数学字体 LaTeX 相对于PlainTeX,它使得科技文档的排版更加直观和方便 ConTeXt 和LaTeX 相比,它更加灵活和自由 ... 发行版 TeX Live 国际TeX用户组织TUG开发,支持不同的操作系统 MiKTeX Windows 下广泛使用的一个TeX发行版 ConTeXt Minimals 它包含了最新版本的 ConTeXt teTeX 一个Unix下的TeX发行版,现在已经停止更新且并入TeXLive fpTeX 一个Windows的TeX发行版,已不再更新 ... 真够乱的,还好,我们只关注一部分: LaTeX 原始的TeX已经有了一组宏集,也就是Knuth所写的著名的Plain TeX(原始的TeX和Plain Tex都是《The TeXbook 》一书中介绍的内容)。 但是这些命令仍然很底层,不够方便、直观,于是Leslie Lamport写了另一组宏,称为LaTeX,主要是它版本配置和文中内容适度分开处理。 LaTeX 2ε是自1993年以来LaTeX的一个稳定版本,是目前大部分LaTeX书籍的主体内容。 ctex ctex宏包提供了一个统一的中文LaTeX文档框架,底层支持CCT、CJK和xeCJK三种中文LaTeX系统。 CCT 非常不推荐了 CJK 这个?应该在windows下工作还很不错 xeCJK 比较推荐 ctex宏包提供了编写中文LaTeX文档常用的一些宏定义和命令。 主要文件包括ctexart.cls、ctexrep.cls、ctexbook.cls 和 ctex.sty、ctexcap.sty。 解决方案 先来看一下sphinx生成pdf的流程: 当执行make latexpdf时,会首先执行sphinx-build生成tex源文件,然后调用_build/latex目录下的makefile文件,利用pdflatex引擎将tex文件转换为PDF。 _build/latex下的Makefile文件是sphinx/texinputs/Makefile的直接拷贝。因而需要修改sphinx/texinputs/Makefile,将其中的pdflatex修改成xelatex。 建议使用编译源码的方式安装sphinx,http://sphinx-doc.org/install.html,可以方便找到Makefile,latex.py等文件。 我们假定你下载的sphinx源码在/opt/sphinx下,后面说的sphinx/texinputs/Makefile等是在sphinx下的 修改Makefile文件 修改sphinx/texinputs/Makefile,将其中的pdflatex修改成xelatex。 (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 修改latex.py 如果make latexpdf时出现下面错误,则是说明没有修改latex.py文件 ! Undefined control sequence. \GenericError ... #4 \errhelp \@err@ ... l.2856 } 修改sphinx/writers/latex.py,在231行左右加入语句对中文做特殊处理: if builder.config.language == 'zh_CN': self.elements['babel'] = '' self.elements['inputenc'] = '' self.elements['utf8extra'] = '' 编译安装sphinx 对sphinx源代码的修改就好了,编译安装sphinx 修改conf.py 编译好后, 使用sphinx-quickstart 建立一个新的sphinx项目,直接make latexpdf之后不会报错,但是中文部分完全没有显示,这是因为缺乏中文所需要的字体设置。修改conf.py中的latex_elements参数,和加上如下:(conf.py是你sphinx项目下的配置文件) (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': '', } # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. language = 'zh_CN' 现在sphinx可以生成中文pdf,包括中文目录。 LATEX Previous post 使用vundle来管理VIM插件 Next post daemontools使用
Leave a Reply
Your email address will not be published. Required fields are marked *, You could login