国产精品综合一区二区,中文精品在线,中文字幕超清在线免费

當初項目文檔是用sphinx寫的，一套rst下來make html得到一整個漂亮的在線文檔。現在想要將文檔導出為離線的handbook pdf，于是找到了rst2pdf這個項目，作為sphinx的拓展，然后加上少量配置即可輸出中文PDF。

rst2pdf

簡介

使用rst2pdf實現將sphinx生成PDF

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

自定義頁面布局
支持層疊樣式表
支持內嵌TTF和Type1字體
支持幾乎所有語言的語法高亮
使用reStructuredText作為源文件
支持字間距調整

安裝

1	`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."