使用rst2pdf實現將sphinx生成PDF

使用rst2pdf實現將sphinx生成PDF

當初專案文件是用sphinx寫的,一套rst下來make html得到一整個漂亮的線上文件。現在想要將文件匯出為離線的handbook pdf,於是找到了rst2pdf這個專案,作為sphinx的拓展,然後加上少量配置即可輸出中文PDF。

rst2pdf

簡介

rst2pdf是一個將 reStructuredText 轉換為 PDF 的工具,具有下列特性:

自定義頁面佈局
支援層疊樣式表
支援內嵌TTF和Type1字型
支援幾乎所有語言的語法高亮
使用reStructuredText作為原始檔
支援字間距調整

安裝


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依然是空白的:

在使用二分法排除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/

您可能感興趣的文章:

sphinx使用及其簡單配置方法Sphinx/MySQL 協議支援與SphinxQL應用例項python將html轉成PDF的實現程式碼(包含中文)深入解析php之sphinxPython生成pdf檔案的方法Python實現批量把SVG格式轉成png、pdf格式的程式碼分享php啟用sphinx全文搜尋的實現方法python使用reportlab實現圖片轉換成pdf的方法