When the project document is written in sphinx, a set of rst down make html to get a whole beautiful online document. Now want to export the document as an offline handbook pdf, so I found the rst2pdf project, as the expansion of sphinx, and then add a small number of configurations to output Chinese PDF.
rst2pdf
summary
rst2pdf is a tool to convert reStructuredText to PDF with the following features:
- Customize page layout
- Cascading Style Sheet Support
- Support embedded TTF and Type1 fonts
- Supports syntax highlighting in almost any language
- Using reStructuredText as the source file
- Support word spacing adjustment
mounting
easy_install rst2pdf
Configure rst2pdf
Register to sphinx project
You need to tell sphinx that we have rst2pdf installed and are using it as a plugin. Just configure it in the project root directory in:
# Add any Sphinx extension module names here, as strings. They can be # extensions coming with Sphinx (named '.*') or your custom # ones. extensions = [ '', '' ]
can be. Then, copy the PDF-related configurations in:
# -- 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'
Please adjust the values of the specific configuration items yourself, you don't need to strictly follow mine.
style sheet
Create a zh_CN.json in the project root directory and write:
{
"embeddedFonts": [
""
],
"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"
}
]
]
}
A note about the above styles:
embeddedFonts is used for embedding fonts, and it has been tested that it must contain at least four values in order not to report an error. However, these four font values can be duplicates.
fontsAlias is used to specify what font to use for each type of glyph. Such as stdFont refers to the body font, stdBold refers to bold, stdItalic refers to italic. Others are stdBoldItalic bold italic, stdMono is wide, and so on. Make sure the fonts you use are installed on your operating system, and the fonts must be of TTF type (Windows environment is more restrictive~).
wordWrap is used to specify the rules of line breaks, CJK is applicable to the rules of Chinese, Japanese and Korean characters. This is a template copied from the Internet, but after my test found that, if you use CJK rules, mixed-arrangement documents in the English part of the normal line breaks, which is a pity. In fact, many of the classification of fontsAlias only English fonts have meaning, such as strictly speaking, Chinese is not the so-called italicized (but because of the popularity of Word, often see the Chinese is set to italicized cases). If it is a purely Chinese document, of course, randomly with which Chinese fonts can be, such as Song. In reality, there are often mixed cases of English and Chinese, so if all the Chinese fonts, the English part of the font can not be displayed in italics and other glyphs.
A note about pdf_stylesheets: some of the styles used by default in this parameter contain fonts that are not found on all operating systems.' sphinx' and 'kerning' are styles provided by default, either do not use them or directly modify the fonts they contain.' a4' means to set the output PDF to A4 paper size. The default style files can be found in the installation path of rst2pdf.
Then configure the compilation script
Windows users, join in the middle:
if "%1" == "pdf" ( %SPHINXBUILD% -b pdf %ALLSPHINXOPTS% %BUILDDIR%/pdf if errorlevel 1 exit /b 1 echo. finished. The pdf files are in %BUILDDIR%/pdf. goto end )
Unix-like user modifies Makefile.
pdf: $(SPHINXBUILD) -b pdf $(ALLSPHINXOPTS) $(BUILDDIR)/pdf @echo @echo "Build finished. The PDF files are in _build/pdf."
Output PDF
And then one sentence:
make pdf
It will be able to output PDF.
Resolved:249 Unknown font.
This should be due to the pdf_font_path configuration error caused by the fact that I am sure that the configuration of the error-free rst2pdf still can not find the font file, so I modified the X:\Program Files (x86)\Python27\Lib\site-packages\rst2pdf\ line 236, in the
fontfile = get_nt_fname(fname)
Added later:
fontfile = 'C:\\Windows\\Fonts\\'
Force the issue.
Solve rst2pdf output PDF as a blank document
In fact, with normal fonts, I found that the output PDF was still blank:
After troubleshooting the problem in the rst file using dichotomy, I found that it was due to the table of contents at the beginning of the PDF. This happens when the table of contents goes beyond one page, and I'm inclined to think it's a bug in rst2pdf.
The solution is to turn pdf_toc_depth down a bit, or simply not generate a catalog, pdf_use_toc = False.
PDF effect
So retry again, you can generate a beautiful PDF:
RELATED:
/cookbook/pdf/
/static/
/sphinx-restructuredtext-pdf-generation-with-rst2pdf/