使用rst2pdf实现将sphinx生成PDF


Posted in Python onJune 07, 2016

当初项目文档是用sphinx写的,一套rst下来make html得到一整个漂亮的在线文档。现在想要将文档导出为离线的handbook pdf,于是找到了rst2pdf这个项目,作为sphinx的拓展,然后加上少量配置即可输出中文PDF。

rst2pdf

简介

使用rst2pdf实现将sphinx生成PDF

rst2pdf是一个将 reStructuredText 转换为 PDF 的工具,具有下列特性:

  1. 自定义页面布局
  2. 支持层叠样式表
  3. 支持内嵌TTF和Type1字体
  4. 支持几乎所有语言的语法高亮
  5. 使用reStructuredText作为源文件
  6. 支持字间距调整

安装

easy_install rst2pdf

配置rst2pdf

注册到sphinx项目

需要告诉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'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
)

类Unix用户修改Makefile:

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'

强行解决问题。

解决rst2pdf输出PDF为空白文档

事实上,在字体正常的情况下,我发现输出的PDF依然是空白的:

使用rst2pdf实现将sphinx生成PDF

在使用二分法排除rst文件中的问题后,我发现这是由于PDF开头的目录造成的。当目录超出一页时就会发生这种情况,我倾向于认为这是rst2pdf的一个bug。

解决方法是将pdf_toc_depth调小一点,或者干脆不生成目录,pdf_use_toc = False。

PDF效果

于是再次重试,可以生成漂亮的PDF了:

使用rst2pdf实现将sphinx生成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/

Python 相关文章推荐
python3访问sina首页中文的处理方法
Feb 24 Python
浅谈Scrapy框架普通反爬虫机制的应对策略
Dec 28 Python
对numpy和pandas中数组的合并和拆分详解
Apr 11 Python
详解python读取和输出到txt
Mar 29 Python
Python面向对象之类的封装操作示例
Jun 08 Python
python实现广度优先搜索过程解析
Oct 19 Python
python中property和setter装饰器用法
Dec 19 Python
python怎么删除缓存文件
Jul 19 Python
Python+pyftpdlib实现局域网文件互传
Aug 24 Python
如何在 Matplotlib 中更改绘图背景的实现
Nov 26 Python
Matplotlib配色之Colormap详解
Jan 05 Python
pandas:get_dummies()与pd.factorize()的用法及区别说明
May 21 Python
python监控文件或目录变化
Jun 07 #Python
浅析Python中的多条件排序实现
Jun 07 #Python
Python卸载模块的方法汇总
Jun 07 #Python
Python运行报错UnicodeDecodeError的解决方法
Jun 07 #Python
PyCharm使用教程之搭建Python开发环境
Jun 07 #Python
Python使用Pycrypto库进行RSA加密的方法详解
Jun 06 #Python
Python的Flask框架应用调用Redis队列数据的方法
Jun 06 #Python
You might like
基于jquery的cookie的用法
2011/01/10 Javascript
JQuery结合CSS操作打印样式的方法
2013/12/24 Javascript
深入理解javascript作用域第二篇之词法作用域和动态作用域
2016/07/24 Javascript
常用的js验证和数据处理总结
2016/08/02 Javascript
微信小程序使用第三方库Underscore.js步骤详解
2016/09/27 Javascript
详解nodejs异步I/O和事件循环
2017/06/07 NodeJs
七行JSON代码把你的网站变成移动应用过程详解
2019/07/09 Javascript
Vue防止白屏添加首屏动画的实例
2019/10/31 Javascript
vue 路由懒加载中给 Webpack Chunks 命名的方法
2020/04/24 Javascript
[02:38]DOTA2亚洲邀请赛 IG战队巡礼
2015/02/03 DOTA
python的re模块应用实例
2014/09/26 Python
python实现简单的socket server实例
2015/04/29 Python
使用Python读写文本文件及编写简单的文本编辑器
2016/03/11 Python
利用python将json数据转换为csv格式的方法
2018/03/22 Python
Python使用matplotlib模块绘制图像并设置标题与坐标轴等信息示例
2018/05/04 Python
python使用Flask操作mysql实现登录功能
2018/05/14 Python
Python 读写文件的操作代码
2018/09/20 Python
对pandas中iloc,loc取数据差别及按条件取值的方法详解
2018/11/06 Python
Python二次规划和线性规划使用实例
2019/12/09 Python
Python字符串、列表、元组、字典、集合的补充实例详解
2019/12/20 Python
tensorflow使用freeze_graph.py将ckpt转为pb文件的方法
2020/04/22 Python
让IE支持CSS3的不完全兼容方案
2014/09/19 HTML / CSS
HTML5实现锚点时请使用id取代name
2013/09/06 HTML / CSS
HTML5 FileReader对象的具体使用方法
2020/05/22 HTML / CSS
Expedia加拿大官方网站:加拿大最大的在线旅游提供商
2017/12/31 全球购物
经典c++面试题五
2014/12/17 面试题
承办会议欢迎词
2014/01/17 职场文书
升旗仪式主持词
2014/03/19 职场文书
公证委托书模板
2014/04/03 职场文书
2014年办公室文秘工作总结
2014/12/09 职场文书
网络营销计划
2015/01/17 职场文书
2015年度学校卫生工作总结
2015/05/12 职场文书
2015年社区反邪教工作总结
2015/10/14 职场文书
2016国庆节活动宣传语
2015/11/25 职场文书
调解协议书范本
2016/03/21 职场文书
5种方法告诉你如何使JavaScript 代码库更干净
2021/09/15 Javascript