当初项目文档是用sphinx写的，一套rst下来make html得到一整个漂亮的在线文档。现在想要将文档导出为离线的handbook pdf，于是找到了rst2pdf这个项目，作为sphinx的拓展，然后加上少量配置即可输出中文PDF。
rst2pdf
简介
rst2pdf是一个将 reStructuredText 转换为 PDF 的工具，具有下列特性：
安装
easy_install rst2pdf
配置rst2pdf
需要告诉sphinx我们安装了rst2pdf，并且将其作为插件使用。只需在项目根目录下的conf.py中配置：
# Add any Sphinx extension module names here,as strings. They can be # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. extensions = [ 'sphinx.ext.autodoc','rst2pdf.pdfbuilder' ]
即可。然后，在conf.py中拷入PDF相关的配置：
# -- Options for PDF output -------------------------------------------------- # Grouping the document tree into PDF files. List of tuples # (source start file,target name,title,author,options). # # If there is more than one author,separate them with \\. # For example: r'Guido van Rossum\\Fred L. Drake,Jr.,editor' # # The options element is a dictionary that lets you override # this config per-document. # For example,# ('index',u'MyProject',u'My Project',u'Author Name',# dict(pdf_compressed = True)) # would mean that specific document would be compressed # regardless of the global pdf_compressed setting. pdf_documents = [ ('index',u'HanLP Handbook',u'hankcs'),] # A comma-separated list of custom stylesheets. Example: pdf_stylesheets = ['a3','zh_CN'] # Create a compressed PDF # Use True/False or 1/0 # Example: compressed=True #pdf_compressed = False # A colon-separated list of folders to search for fonts. Example: pdf_font_path = ['C:\\Windows\\Fonts'] # Language to be used for hyphenation support pdf_language = "zh_CN" # Mode for literal blocks wider than the frame. Can be # overflow,shrink or truncate pdf_fit_mode = "shrink" # Section level that forces a break page. # For example: 1 means top-level sections start in a new page # 0 means disabled #pdf_break_level = 0 # When a section starts in a new page,force it to be 'even','odd',# or just use 'any' #pdf_breakside = 'any' # Insert footnotes where they are defined instead of # at the end. #pdf_inline_footnotes = True # verbosity level. 0 1 or 2 #pdf_verbosity = 0 # If false,no index is generated. #pdf_use_index = True # If false,no modindex is generated. #pdf_use_modindex = True # If false,no coverpage is generated. #pdf_use_coverpage = True # Documents to append as an appendix to all manuals. #pdf_appendices = [] # Enable experimental feature to split table cells. Use it # if you get "DelayedTable too big" errors #pdf_splittables = False # Set the default DPI for images #pdf_default_dpi = 72 # Enable rst2pdf extension modules (default is only vectorpdf) # you need vectorpdf if you want to use sphinx's graphviz support #pdf_extensions = ['vectorpdf'] # Page template name for "regular" pages #pdf_page_template = 'cutePage' # Show Table Of Contents at the beginning? # pdf_use_toc = False # How many levels deep should the table of contents be? pdf_toc_depth = 2 # Add section number to section references pdf_use_numbered_links = False # Background images fitting mode pdf_fit_background_mode = 'scale'
具体配置项的值请自行调整，不需要严格按照我的来。
样式表
在项目根目录下创建一个zh_CN.json，写入：
{
"embeddedFonts": [
"simsun.ttc"
],"fontsAlias": {
"stdFont": "simsun","stdBold": "simsun","stdItalic": "simsun","stdBoldItalic": "simsun","stdMono": "simsun","stdMonoBold": "simsun","stdMonoItalic": "simsun","stdMonoBoldItalic": "simsun","stdSans": "simsun","stdSansBold": "simsun","stdSansItalic": "simsun","stdSansBoldItalic": "simsun"
},"styles": [
[
"base",{
"wordWrap": "CJK"
}
],[
"literal",{
"wordWrap": "None"
}
]
]
}
关于以上样式的说明：
embeddedFonts用于嵌入字体，经试验，必须包含至少四个值才不会报错。不过这四个字体值可以是重复的。
fontsAlias用来指定各类字形用什么字体。如stdFont指正文字体，stdBold指粗体，stdItalic指斜体。其他的还有stdBoldItalic粗斜体，stdMono等宽体，等等。确保所用字体已经安装在你的操作系统上，且字体必须是TTF类型的（Windows环境下限制比较多~）。
wordWrap用于指定换行规则，CJK就是适用于中日韩文字的规则。这是从网上的模板抄来的，但经我的测试发现，如果用CJK规则的话，中英混排的文档里面英文部分就没法正常断行，这真是个遗憾。实际上，fontsAlias的分类很多都只对英文字体有意义，如严格来讲中文是没有所谓斜体的（不过因为Word的普及，经常看到中文被设置为斜体的情形）。如果是纯中文文档，当然随便用哪些中文字体都行，如宋体。现实中，经常会有中英文混排的情形，所以如果全用中文字体的话，英文部分就没法显示斜体等字形了。
关于pdf_stylesheets的说明：这个参数中默认使用的某些样式包含了一些字体，而这些字体并非在所有操作系统上都找得到。'sphinx'和'kerning'都是默认提供的样式，要么不用它们，要么直接修改其包含的字体。'a4'指设置输出的PDF为A4纸大小。默认的样式文件可以在rst2pdf的安装路径下找到。
然后配置编译脚本
Windows用户，在make.bat中加入：
if "%1" == "pdf" ( %sphinxBUILD% -b pdf %ALLSphinxOPTS% %BUILDDIR%/pdf if errorlevel 1 exit /b 1 echo. echo.Build finished. The pdf files are in %BUILDDIR%/pdf. goto end )
pdf: $(SphinxBUILD) -b pdf $(ALLSphinxOPTS) $(BUILDDIR)/pdf @echo @echo "Build finished. The PDF files are in _build/pdf."
输出PDF
然后一句：
make pdf
就能输出PDF了。
解决findfonts.py:249 UnkNown font:
这应该是由于pdf_font_path配置有误造成的，事实上，我确定配置无误rst2pdf还是找不到字体文件，于是我修改了X:\Program Files (x86)\Python27\Lib\site-packages\rst2pdf\findfonts.py第236行，在
fontfile = get_nt_fname(fname)
后面加了一句：
fontfile = 'C:\\Windows\\Fonts\\simsun.ttc'
强行解决问题。
事实上，在字体正常的情况下，我发现输出的PDF依然是空白的：
在使用二分法排除rst文件中的问题后，我发现这是由于PDF开头的目录造成的。当目录超出一页时就会发生这种情况，我倾向于认为这是rst2pdf的一个bug。
解决方法是将pdf_toc_depth调小一点，或者干脆不生成目录，pdf_use_toc = False。
PDF效果
于是再次重试，可以生成漂亮的PDF了：
相关链接：
http://sphinx-users.jp/cookbook/pdf/rst2pdf.html
http://ralsina.me/static/manual.pdf
http://www.typemylife.com/sphinx-restructuredtext-pdf-generation-with-rst2pdf/
版权声明：本文内容由互联网用户自发贡献，该文观点与技术仅代表作者本人。本站仅提供信息存储空间服务，不拥有所有权，不承担相关法律责任。如发现本站有涉嫌侵权/违法违规的内容， 请发送邮件至 dio@foxmail.com 举报，一经查实，本站将立刻删除。
