Use rst2pdf to generate a PDF file and rst2?sph=

Use rst2pdf to generate a PDF file and rst2?sph=

At the beginning, the project documentation was written using sphinx. After a set of rst, make html to get a complete and beautiful online document. Now I want to export the document as an offline handbook pdf, so I found the rst2pdf project as an extension of sphinx, and then added a few configurations to output the Chinese PDF.

Rst2pdf

Introduction

Rst2pdf is a tool for converting reStructuredText to PDF. It has the following features:

1. Custom page layout
2. Supports Cascading Style Sheets
3. Supports embedded TTF and Type1 Fonts
4. Supports syntax highlighting in almost all languages
5. Use reStructuredText as the source file
6. Supports font spacing adjustment

Install

easy_install rst2pdf

Configure rst2pdf

Register with the sphinx Project

We need to inform sphinx that we have installed rst2pdf and used it as a plug-in. You only need to configure in conf. py under the project root directory:

# 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']

You can. Then, in conf. py, configure the PDF Configuration:

# -- 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 supportpdf_language = "zh_CN" # Mode for literal blocks wider than the frame. Can be# overflow, shrink or truncatepdf_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 referencespdf_use_numbered_links = False # Background images fitting modepdf_fit_background_mode = 'scale'

Adjust the value of the specific configuration item by yourself.

Style Sheet

Create a zh_CN.json file in the root directory of the project and write it:

{ "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"   }  ] ]}

Description of the above style:

EmbeddedFonts is used to embed a font. After testing, it must contain at least four values to avoid errors. However, the four font values can be repeated.

FontsAlias is used to specify the fonts used for various fonts. For example, stdFont indicates the text font, stdBold indicates the bold text, and stdItalic indicates the italic. Other wide bodies such as stdBoldItalic bold italic and stdMono. Make sure that the font you use has been installed on your operating system, and the font must be of the TTF type (in Windows, there are many restrictions ~).

WordWrap is used to specify line feed rules. CJK is the rule applicable to Chinese and Japanese characters. This was copied from the template on the Internet. However, my test showed that if the CJK rule is used, the English part of the documents in the Chinese-English hybrid sorting cannot be broken normally. This is really a pity. In fact, many types of fontsAlias only make sense for English fonts. For example, Chinese characters do not have any italics (but because of the popularity of Word, it is often seen that Chinese characters are set to italics ). If it is a pure Chinese document, of course you can use any Chinese font, such as. In reality, Chinese and English are often mixed, so if all Chinese fonts are used, the English part will not be able to display italics and other fonts.

Description of pdf_stylesheets: Some styles used by default in this parameter contain fonts that are not found on all operating systems. Both 'sphstyle' and 'kerning' are provided by default. Either they are not used or the fonts contained in them are directly modified. 'A4 'indicates that the size of the output PDF file is a4 paper. The default style file can be found in the installation path of rst2pdf.

Then configure the compilation script

For Windows users, add:

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)

Modify Makefile for Unix-like users:

pdf:  $(SPHINXBUILD) -b pdf $(ALLSPHINXOPTS) $(BUILDDIR)/pdf  @echo  @echo "Build finished. The PDF files are in _build/pdf."

Output PDF

Then, the following sentence is displayed:

make pdf

The PDF file can be output.

Solution: findfonts. py: 249 Unknown font:

This should be caused by incorrect configuration of performance_font_path. In fact, I am sure the rst2pdf configuration is correct or I still cannot find the font file, so I modified X: \ Program Files (x86) \ Python27 \ Lib \ site-packages \ rst2pdf \ findfonts. py row 236th, in

Fontfile = get_nt_fname (fname)

A sentence is added:

Fontfile = 'C: \ Windows \ Fonts \ simsun. ttc'

Solve the problem forcibly.

Solve rst2pdf output PDF as blank document

In fact, when the font is normal, I found that the output PDF is still blank:

After using the binary method to exclude problems in the rst file, I found that this is caused by the directory at the beginning of the PDF file. This happens when the directory exceeds one page. I tend to think this is a bug in rst2pdf.

The solution is to reduce pai_toc_depth or simply not generate a directory. pai_use_toc = False.

PDF Effect

So try again to generate a beautiful PDF:

Related links:

Http://sphinx-users.jp/cookbook/pdf/rst2pdf.html

Http://ralsina.me/static/manual.pdf

Http://www.typemylife.com/sphinx-restructuredtext-pdf-generation-with-rst2pdf/