(8日目) Sphinx から PDF を生成してみよう (rst2pdf 編)
今日のアドベントカレンダーでは Sphinx で PDF 出力する方法をご紹介します。
Sphinx から PDF を出力するには 2種類の方法があります。
ひとつは Sphinx 標準で提供されている LaTeX 経由で PDF を出力する方法です。
もうひとつは rst2pdf をインストールし、rst2pdf の Sphinx 拡張機能を用いる方法です。
二通りある PDF 出力について、僕は次のような印象を持っています。*1
- LaTeX 経由
- rst2pdf 経由
なお、第三勢力の座を sphinxcontrib-docxbuilder が狙っています。
こちらの特徴はこんな感じです。
- sphinxcontrib-docxbuilder
- MS-Word の機能を用いて PDF 出力する
- Word のデザインテンプレートを使うのでデザイン調整がしやすい
- でもバージョンがまだ 0.0.1alpha 。
今日はこれらのうち、rst2pdf を使った PDF 出力を取り上げてみようと思います。
rst2pdf とは
rst2pdf は Roberto Alsina さんが開発したツールで、reST 形式のテキストから PDF を生成するツールです。
Sphinx は標準の reST に対して独自の拡張(ディレクティブやロールなど)を加えていますが、rst2pdf は標準の reST が対象になります。
本来は rst2pdf は単体で利用するツールですが、PDF 出力部分を Sphinx から利用できるよう Sphinx 拡張を提供しているため、
Sphinx から利用することも出来ます。
rst2pdf を使ってみる
Debian squeeze では rst2pdf パッケージが存在しますが、少しバージョンが古いので easy_install を使います。
依存パッケージである reportlab と PIL はビルドに時間がかかるので、こちらは apt でインストールします。
$ sudo apt-get install python-reportlab pythong-imaging
$ sudo easy_install rst2pdf
次に日本語用の設定ファイルを作成します。
デフォルトでは rst2pdf は日本語が利用できないようになっているので、
フォントの設定をする必要があります。
ja.json というファイル名で以下の内容を保存します。
{
"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"
}]
]
}それでは試しに rst2pdf を単体で利用してみます。
サンプルとして次のような reST ファイルを用意しました。
=============================
rst2pdf sample documentation
=============================
これは rst2pdf を利用するサンプルです。
blockdiag の紹介
=================
blockdiag シリーズは以下のパッケージから構成されています。
* blockdiag
* seqdiag
* actdiag
* nwdiag
* nwdiag
* rackdiag
blockdiag パッケージとコマンド群
=================================
もちろん表も書けます。
============ =========
パッケージ名 コマンド
============ =========
blockdiag blockdiag
seqdiag seqdiag
actdag actdiag
nwdiag nwdiag
rackdiag
============ =========ではこのファイル(blockdiag.rst)を PDF に変換してみます。
$ rst2pdf -s ja blockdiag.rst
生成された PDF (blockdiag.pdf) はこのような表示になります。
Sphinx から使ってみよう
rst2pdf を Sphinx から利用する際はいくつか設定が必要です。
- conf.py の書き換え
- Makefile の書き換え
- ja.json の作成
それぞれについて順番に説明していきます。
conf.py の書き換え
まずは rst2pdf を有効にするため conf.py を編集します。
ここで、かならず pdf_stylesheets の設定を忘れないようにしてください。
rst2pdf 単体と同じように日本語を有効にする設定('ja')が含まれています。
extensions += ['rst2pdf.pdfbuilder']
pdf_documents = [
('index', u'MyProject', u'My Project', u'Author Name'),
]
# A comma-separated list of custom stylesheets.
pdf_stylesheets = ['sphinx', 'kerning', 'a4', 'ja']
# Language to be used for hyphenation support
pdf_language = "ja"また、前述の ja.json を Sphinx プロジェクトのディレクトリにコピーしておきます。
Makefile の書き換え
Makefile には rst2pdf 経由でビルドする make ターゲットが記述されていないので、
Makefile に pdf ターゲットを追加します。
pdf:
$(SPHINXBUILD) -b pdf $(ALLSPHINXOPTS) $(BUILDDIR)/pdf
@echo
@echo "Build finished. The PDF files are in _build/pdf."引数なしで make コマンドを実行した時に表示されるヘルプに
pdf がリストアップされないのが気になる人は help ターゲットに
@echo " pdf to make pdf file"
を足しておくとよいかもしれません。
ここまで設定すると make pdf すると Sphinx ドキュメントを PDF 出力することができます。
$ make pdf bin/sphinx-build -b pdf -d _build/doctrees . _build/pdf Running Sphinx v1.1.2 loading translations [ja]... done loading pickled environment... done building [pdf]: targets for 1 source files that are out of date updating environment: 0 added, 1 changed, 1 removed reading sources... [100%] index looking for now-outdated files... none found pickling environment... done checking consistency... done processing MyProject... index resolving references... done writing MyProject... done build succeeded. Build finished. The PDF files are in _build/pdf. $ ls _build/pdf MyProject.pdf
Sphinx 経由で出力すると表紙や目次が付きます。
これらが不要な場合は conf.py の設定で調整することができます。
# 表紙を出力しない pdf_use_coverpage = False # 目次を出力しない pdf_use_toc = False
エラーが出る人へ
rst2pdf と docutils-0.8 以降の組み合わせでは、以下のようなエラーが発生します。
$ make pdf bin/sphinx-build -b pdf -d _build/doctrees . _build/pdf Running Sphinx v1.1.2 loading translations [ja]... done loading pickled environment... done building [pdf]: targets for 2 source files that are out of date updating environment: 0 added, 0 changed, 0 removed looking for now-outdated files... none found processing MyProject... index [ERROR] pdfbuilder.py:129 get_language() takes exactly 2 arguments (1 given) Traceback (most recent call last): File "/home/katsuwo/.buildout/buildout-eggs/rst2pdf-0.16-py2.6.egg/rst2pdf/pdfbuilder.py", line 121, in write appendices=opts.get('pdf_appendices', self.config.pdf_appendices) or []) File "/home/katsuwo/.buildout/buildout-eggs/rst2pdf-0.16-py2.6.egg/rst2pdf/pdfbuilder.py", line 188, in assemble_doctree self.docutils_languages[lang] = get_language(lang) TypeError: get_language() takes exactly 2 arguments (1 given) FAILED build succeeded.
この問題に対する修正が提供されているので、docutils に回避用のパッチを適用するとよいでしょう。
さて、今日は rst2pdf を使って PDF 出力する方法をご紹介しました。
標準で利用できる HTML や ePub とあわせて、よく利用する方法だと思います。
ぜひ利用してみてください。
