rst2pdf拡張を使ったPDFファイル作成

日時:2010/09/19
作者:池 徹
最終更新:2012/02/15

Sphinxはrst2pdfと連携することによりPDFを出力することができます。

rst2pdfのインストール

SphinxでPDFを作成するためにはrst2pdfをインストールします。通常のeasy_install(もしくはdistribute, pip)を利用したインストール方法でインストールできます。

$ sudo easy_install rst2pdf

なお、rst2pdfは、Python用のPDF作成ライブラリである、reportlabに依存していますが、easy_installでインストールした際には依存ライブラリも解消してくれます。

日本語フォントのインストール

例として、今回はVLゴシックフォントIPAフォントをインストールします。

VLゴシックフォント

ダウンロード解凍後に、フォントディレクトリにコピーします。

wget http://jaist.dl.sourceforge.jp/vlgothic/44715/VLGothic-20091202.zip
#curl -O http://jaist.dl.sourceforge.jp/vlgothic/44715/VLGothic-20091202.zip
unzip VLGothic-20091202.zip
cd VLGothic
cp *.ttf /usr/share/fonts/

注釈

手元のFedora13ではVLGothicフォントが/usr/share/fonts/vlgothic/に既にインストール済みでした。

IPAフォント

ダウンロード解凍後に、フォントディレクトリにコピーします。

wget http://info.openlab.ipa.go.jp/ipafont/fontdata/IPAfont00301.zip
unzip IPAfont00301.zip
cd IPAfont00301
cp *.otf /usr/share/fonts/

プロジェクトの作成

通常通り、sphinx-quickstartコマンドを使ってドキュメントのプロジェクトフォルダの環境を設定します。後はチュートリアルなどを見ながら、通常通りにSphinxを使ってドキュメントを書き上げていきます。make htmlを使ってプレビューをしながら書いていくのが良いでしょう。

PDFの設定を追加

conf.pyにPDF用の設定を自分で書き加える必要があります。

まずはrst2pdf.pdfbuilderconf.pyextensionsに追加します。

extensions = ['rst2pdf.pdfbuilder']

次に、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'MyProject', u'My Project', u'Author Name'),
]

# A comma-separated list of custom stylesheets. Example:
pdf_stylesheets = ['sphinx','kerning','a4','ja']

# 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 = ['/usr/share/fonts']

# Language to be used for hyphenation support
pdf_language = "ja"

# 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

注釈

詳細は、How to use rst2pdfの項目Sphinxを参照にするとよいでしょう。

コマンドの追加

MakefileにPDFのコマンドを追加します。

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

スタイルシートの設定

作成したプロジェクトの直下にja.jsonを作成し設定を追加します。

{
    "embeddedFonts" : [
        "VL-Gothic-Regular.ttf",
        "VL-PGothic-Regular.ttf",
        "ipam.otf",
        "ipag.otf",
        "ipagp.otf",
        "ipamp.otf"
    ],
    "fontsAlias" : {
        "stdFont": "VL-PGothic-Regular",
        "stdBold": "VL-PGothic-Regular",
        "stdItalic": "VL-PGothic-Regular",
        "stdBoldItalic": "VL-PGothic-Regular",
        "stdMono": "VL-Gothic-Regular",
        "stdMonoBold": "VL-Gothic-Regular",
        "stdMonoItalic": "VL-Gothic-Regular",
        "stdMonoBoldItalic": "VL-Gothic-Regular",
        "stdSans": "VL-Gothic-Regular",
        "stdSansBold": "VL-Gothic-Regular",
        "stdSansItalic": "VL-Gothic-Regular",
        "stdSansBoldItalic": "VL-Gothic-Regular"
    },
    "styles" : [
        ["base" , {
            "wordWrap": "CJK"
        }],
        ["literal" , {
            "wordWrap": "None"
        }]
     ]
 }

ビルドと確認

いつものようにmakeします。ビルダー名はpdfになります。

[rokujyouhitoma@localhost docs]# make pdf
sphinx-build -b pdf -d build/doctrees   source _build/pdf
Running Sphinx v1.0.4
(中略)
build succeeded.

Build finished. The PDF files are in _build/pdf.

_build/pdf/フォルダの下にpdfファイルが作成されます。

変更履歴

2010/09/19:初版(池 徹)
2010/10/09:rst2pdf経由ということでタイトル変更。(渋川)
2012/02/15:conf.py およびスタイルシートの設定を更新。(小宮)