使用rst2pdf實(shí)現(xiàn)將sphinx生成PDF
當(dāng)初項(xiàng)目文檔是用sphinx寫(xiě)的,一套rst下來(lái)make html得到一整個(gè)漂亮的在線文檔。現(xiàn)在想要將文檔導(dǎo)出為離線的handbook pdf,于是找到了rst2pdf這個(gè)項(xiàng)目,作為sphinx的拓展,然后加上少量配置即可輸出中文PDF。
rst2pdf
簡(jiǎn)介
rst2pdf是一個(gè)將 reStructuredText 轉(zhuǎn)換為 PDF 的工具,具有下列特性:
- 自定義頁(yè)面布局
- 支持層疊樣式表
- 支持內(nèi)嵌TTF和Type1字體
- 支持幾乎所有語(yǔ)言的語(yǔ)法高亮
- 使用reStructuredText作為源文件
- 支持字間距調(diào)整
安裝
easy_install rst2pdf
配置rst2pdf
注冊(cè)到sphinx項(xiàng)目
需要告訴sphinx我們安裝了rst2pdf,并且將其作為插件使用。只需在項(xiàng)目根目錄下的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相關(guān)的配置:
# -- 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'
具體配置項(xiàng)的值請(qǐng)自行調(diào)整,不需要嚴(yán)格按照我的來(lái)。
樣式表
在項(xiàng)目根目錄下創(chuàng)建一個(gè)zh_CN.json,寫(xiě)入:
{ "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" } ] ] }
關(guān)于以上樣式的說(shuō)明:
embeddedFonts用于嵌入字體,經(jīng)試驗(yàn),必須包含至少四個(gè)值才不會(huì)報(bào)錯(cuò)。不過(guò)這四個(gè)字體值可以是重復(fù)的。
fontsAlias用來(lái)指定各類字形用什么字體。如stdFont指正文字體,stdBold指粗體,stdItalic指斜體。其他的還有stdBoldItalic粗斜體,stdMono等寬體,等等。確保所用字體已經(jīng)安裝在你的操作系統(tǒng)上,且字體必須是TTF類型的(Windows環(huán)境下限制比較多~)。
wordWrap用于指定換行規(guī)則,CJK就是適用于中日韓文字的規(guī)則。這是從網(wǎng)上的模板抄來(lái)的,但經(jīng)我的測(cè)試發(fā)現(xiàn),如果用CJK規(guī)則的話,中英混排的文檔里面英文部分就沒(méi)法正常斷行,這真是個(gè)遺憾。實(shí)際上,fontsAlias的分類很多都只對(duì)英文字體有意義,如嚴(yán)格來(lái)講中文是沒(méi)有所謂斜體的(不過(guò)因?yàn)閃ord的普及,經(jīng)常看到中文被設(shè)置為斜體的情形)。如果是純中文文檔,當(dāng)然隨便用哪些中文字體都行,如宋體?,F(xiàn)實(shí)中,經(jīng)常會(huì)有中英文混排的情形,所以如果全用中文字體的話,英文部分就沒(méi)法顯示斜體等字形了。
關(guān)于pdf_stylesheets的說(shuō)明:這個(gè)參數(shù)中默認(rèn)使用的某些樣式包含了一些字體,而這些字體并非在所有操作系統(tǒng)上都找得到。'sphinx'和'kerning'都是默認(rèn)提供的樣式,要么不用它們,要么直接修改其包含的字體。'a4'指設(shè)置輸出的PDF為A4紙大小。默認(rèn)的樣式文件可以在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:
這應(yīng)該是由于pdf_font_path配置有誤造成的,事實(shí)上,我確定配置無(wú)誤rst2pdf還是找不到字體文件,于是我修改了X:\Program Files (x86)\Python27\Lib\site-packages\rst2pdf\findfonts.py第236行,在
fontfile = get_nt_fname(fname)
后面加了一句:
fontfile = 'C:\\Windows\\Fonts\\simsun.ttc'
強(qiáng)行解決問(wèn)題。
解決rst2pdf輸出PDF為空白文檔
事實(shí)上,在字體正常的情況下,我發(fā)現(xiàn)輸出的PDF依然是空白的:
在使用二分法排除rst文件中的問(wèn)題后,我發(fā)現(xiàn)這是由于PDF開(kāi)頭的目錄造成的。當(dāng)目錄超出一頁(yè)時(shí)就會(huì)發(fā)生這種情況,我傾向于認(rèn)為這是rst2pdf的一個(gè)bug。
解決方法是將pdf_toc_depth調(diào)小一點(diǎn),或者干脆不生成目錄,pdf_use_toc = False。
PDF效果
于是再次重試,可以生成漂亮的PDF了:
相關(guān)鏈接:
http://sphinx-users.jp/cookbook/pdf/rst2pdf.html
http://ralsina.me/static/manual.pdf
http://www.typemylife.com/sphinx-restructuredtext-pdf-generation-with-rst2pdf/
- 淺談Coreseek、Sphinx-for-chinaese、Sphinx+Scws的區(qū)別
- centos+php+coreseek+sphinx+mysql之一coreseek安裝篇
- 在MySQL中使用Sphinx實(shí)現(xiàn)多線程搜索的方法
- php啟用sphinx全文搜索的實(shí)現(xiàn)方法
- 關(guān)于Sphinx創(chuàng)建全文檢索的索引介紹
- 深入解析php之sphinx
- sphinxql如何得到結(jié)果數(shù)及show meta的詳細(xì)說(shuō)明
- Sphinx/MySQL 協(xié)議支持與SphinxQL應(yīng)用實(shí)例
- sphinx增量索引的一個(gè)問(wèn)題
- Python Sphinx使用實(shí)例及問(wèn)題解決
相關(guān)文章
Python lxml解析HTML并用xpath獲取元素的方法
今天小編就為大家分享一篇Python lxml解析HTML并用xpath獲取元素的方法,具有很好的參考價(jià)值,希望對(duì)大家有所幫助。一起跟隨小編過(guò)來(lái)看看吧2019-01-01Python實(shí)現(xiàn)的列表排序、反轉(zhuǎn)操作示例
這篇文章主要介紹了Python實(shí)現(xiàn)的列表排序、反轉(zhuǎn)操作,結(jié)合實(shí)例形式分析了Python針對(duì)列表的sort排序、以及基于reverse、切片的反轉(zhuǎn)操作相關(guān)實(shí)現(xiàn)技巧,需要的朋友可以參考下2019-03-03selenium使用chrome瀏覽器測(cè)試(附chromedriver與chrome的對(duì)應(yīng)關(guān)系表)
這篇文章主要介紹了selenium使用chrome瀏覽器測(cè)試(附chromedriver與chrome的對(duì)應(yīng)關(guān)系表),小編覺(jué)得挺不錯(cuò)的,現(xiàn)在分享給大家,也給大家做個(gè)參考。一起跟隨小編過(guò)來(lái)看看吧2018-11-11純用NumPy實(shí)現(xiàn)神經(jīng)網(wǎng)絡(luò)的示例代碼
這篇文章主要介紹了純用NumPy實(shí)現(xiàn)神經(jīng)網(wǎng)絡(luò)的示例代碼,小編覺(jué)得挺不錯(cuò)的,現(xiàn)在分享給大家,也給大家做個(gè)參考。一起跟隨小編過(guò)來(lái)看看吧2018-10-10python實(shí)現(xiàn)將html表格轉(zhuǎn)換成CSV文件的方法
這篇文章主要介紹了python實(shí)現(xiàn)將html表格轉(zhuǎn)換成CSV文件的方法,涉及Python操作csv文件的相關(guān)技巧,需要的朋友可以參考下2015-06-06Python OpenCV實(shí)現(xiàn)基于模板的圖像拼接
基于特征點(diǎn)的圖像拼接如果是多張圖,每次計(jì)算變換矩陣,都有誤差,最后可以圖像拼完就變形很大,基于模板的方法可以很好的解決這一問(wèn)題,本文就來(lái)和大家具體聊聊2022-10-10簡(jiǎn)單了解什么是神經(jīng)網(wǎng)絡(luò)
這篇文章主要介紹了簡(jiǎn)單了解什么是神經(jīng)網(wǎng)絡(luò),具有一定借鑒價(jià)值,需要的朋友可以參考下。2017-12-12