rst2pdf で reStructuredText から PDF を生成する : 紹介マニア

概要
インストール
出力スタイルの設定
- 日本語出力のためのスタイル設定
- フォントの埋め込み
rst2pdf の設定ファイル
画像の扱い
- さらなる画像サポートの追加
ソースコードの色付け
ハイフネーション
Sphinx からの利用
変更履歴

概要

rst2pdf は reStructuredText (reST) 形式のファイルを直接 PDF として出力するプログラムです。

この文書では reStructuredText は知っている前提で、 rst2pdf のバージョン 0.15 を対象に、インストールから、設定、基本的な利用方法までを記述します。

rst2pdf と組みあわせると Sphinx から PDF を生成することも可能です。 Sphinx に関しては、 Python ドキュメント生成システム Sphinx を参照してください。

インストール

rst2pdf のインストールには最低限以下の物が必要です。

パッケージシステムを利用してのインストール

fink や MacPorts を利用していれば easy_install を利用してインストールできます。

以下は fink と easy_install を利用してのインストール手順です。

sudo fink install jpeg
sudo fink install freetype219
sudo fink install lcms
sudo easy_install -UZ PIL
sudo easy_install -UZ reportlab
sudo easy_install -UZ rst2pdf

fink や easy_install のバージョンに問題がなければ正常にインストールされます。

ソースをダウンロードしてインストール

fink や MacPorts を利用していない場合必要なライブラリを自分でビルドしないといけません。

easy_install でエラーが発生するなどの理由でソースコードをダウンロードしてきてビルドする必要があるかもしれません。

以下は関連ライブラリ等をコンパイルする手順です。

curl -O http://www.ijg.org/files/jpegsrc.v7.tar.gz
tar zxvf jpegsrc.v7.tar.gz
cd jpeg-7
./configure --enable-shared --enable-static
make
sudo make install

curl -O http://www.littlecms.com/lcms-1.19.tar.gz
tar xvfz lcms-1.19.tar.gz
cd lcms-1.19
./configure
make
sudo make install

curl -O http://effbot.org/downloads/Imaging-1.1.7.tar.gz
tar xvfz Imaging-1.1.7.tar.gz
cd Imaging-1.1.7
vi setup.py
# lib の部分を書き変えます
# JPEG_ROOT = libinclude("/usr/local/lib/")
# FREETYPE_ROOT = libinclude("/Developer/SDKs/MacOSX10.5.sdk/usr/X11/")
# LCMS_ROOT = libinclude("/usr/local/lib/")
sudo python setup.py install

curl -O http://www.reportlab.com/ftp/ReportLab_2_4.tar.gz
tar xvfz ReportLab_2_4.tar.gz
cd ReportLab_2_4
sudo python setup.py install

curl -O http://rst2pdf.googlecode.com/files/rst2pdf-0.15.tar.gz
tar xvfz rst2pdf-0.15.tar.gz
cd rst2pdf-0.15
sudo python setup.py install

動作確認

簡単に動作確認をします。

以下のようなファイルを sample.rst という名前で用意します。

まだここでは日本語を含めないでください。設定を追加しないと日本語を含めても正常にフォントが表示されません。

test
============
sample

rst2pdf sample.rst

sample.pdf の名前で正常に PDF が生成されたことを確認してください。

トラブルシューティング

簡単なサンプルでもエラーが発生する場合があります。

Symbol not found: _jpeg_resync_to_restart

のようなエラーが出る場合は、ターミナル上で Python を起動して以下を実施してみてください。

import _imaging

これで同様のエラーがでる場合は jpeg ライブラリーがインストールされていないか、上手くコンパイルされていない可能性があります。

Python の存在するパスに対して、otool して _imaging.so ファイルが正常であるか確認します。

Python のインストール環境によってパスが異なる可能性があります。

otool -L /Library/Python/2.6/site-packages/site-packages/PIL/_imaging.so
#もしくは
otool -L /Library/Frameworks/Python.framework/Versions/2.6/lib/python2.6/site-packages/PIL/_imaging.so

出力の中に jpeg ライブラリ関連の出力があるか確認してください。例えば以下のような出力になります。

/Library/Frameworks/Python.framework/Versions/2.6/lib/python2.6/site-packages/PIL/_imaging.so:
       /sw/lib/libjpeg.62.dylib (compatibility version 63.0.0, current version 63.0.0)
       /usr/lib/libz.1.dylib (compatibility version 1.0.0, current version 1.2.3)
       /usr/lib/libgcc_s.1.dylib (compatibility version 1.0.0, current version 103.0.0)
       /usr/lib/libSystem.B.dylib (compatibility version 1.0.0, current version 125.0.0)

jpeg 関連の出力が無い場合は PIL のインストール時の setup.py でライブラリのパスの設定が間違っている可能性があります。

PIL をビルドした時 jpeg が OK と出力されていることを確認してください。

出力スタイルの設定

HTML の CSS のように PDF 出力を正常に行なうためにはスタイルの設定が必要です。

日本語出力のためのスタイル設定

初期のスタイルを確認したい場合は以下のコマンドでファイルに出力することができます。

スタイルは json 形式です。

rst2pdf --print-stylesheet > default.json

この設定を上書きするファイルを生成します。ja.json の名前で以下のようなファイルを作成してください。

{
 "fontsAlias" : {
   "stdFont": "M+2P+IPAG",
   "stdBold": "M+2P+IPAG",
   "stdItalic": "M+2P+IPAG",
   "stdBoldItalic": "M+2P+IPAG",
   "stdMono": "M+2P+IPAG-circle"
 },
 "styles" : [
   ["base" , {
     "wordWrap": "CJK"
   }],
   ["literal" , {
     "wordWrap": "None"
   }]
 ]
}

M+ と IPAフォントの合成フォントから TrueType 形式のフォントをダウンロードしてきて、任意の場所に置きます。 フォントをシステムにインストールする必要はありません 。

sample.rst に日本語を記述します。

test
============
sample
日本語のサンプルです

ja.json は sample.rst と同じディレクトリに置きます。

rst2pdf -s ja --font-path=/path/to/fonts sample.rst

PDFが生成されます。エラーが出る場合はインストールの章を再度確認して、正常にインストールされていることを確かめてください。特にフォントのエラーの場合は freetype が正常にインストールされていない場合があります。

フォントの埋め込み

フォントの埋め込みをしたい場合は以下のようなファイルを作成します。

{
 "embeddedFonts" :
 [["M+2P+IPAG.ttf","M+2P+IPAG.ttf","M+2P+IPAG.ttf","M+2P+IPAG-circle.ttf"]],
  "fontsAlias" : {
    "stdFont": "M+2P+IPAG",
    "stdBold": "M+2P+IPAG",
    "stdItalic": "M+2P+IPAG",
    "stdBoldItalic": "M+2P+IPAG",
    "stdMono": "M+2P+IPAG-circle"
  },
  "styles" : [
    ["base" , {
      "wordWrap": "CJK"
    }],
    ["literal" , {
      "wordWrap": "None"
    }]
  ]
}

PDF の生成手順は同じです。

rst2pdf -s ja --font-path=/path/to/fonts sample.rst

rst2pdf の設定ファイル

毎回 font-path や stylesheets を指定するのは面倒なので、設定ファイルを書いておくことでオプション無しで設定が反映されます。

設定ファイルは /etc/rst2pdf か、 ~/.rst2pdf/config の中から読みます。

~/.rst2pdf/config に設定しておくのが良いでしょう。

設定ファイルのサンプルは以下になります。

[general]
stylesheets="ja"
compressed=false
font_path="/path/to/fonts"
header=None
footer=None
fit_mode="shrink"
break_level=0

画像の扱い

画像を PDF に埋めこんでみます。

画像はなんでも良いですが、とりあえず Imaging-1.1.7.tar.gz の中の Images フォルダの中か、 http://hg.effbot.org/pil-2009-raclette/src/tip/Images/ から lena.gif、lena.png、lena.jpg、lena.ppm を取得します。

lena の画像が宗教的な理由や感情的な理由等で駄目な人は別の画像でも問題ありません。 PIL がサポートしているフォーマットに関しては PIL Handbook を参照してください。

sample.rst を以下のようにして、同様に PDF を生成します。

test
============
sample

こんにちはこんにちは

.. image:: Images/lena.gif

.. image:: Images/lena.jpg

.. image:: Images/lena.png

.. image:: Images/lena.ppm

以下のような WARNING が発生するかもしれません。

[WARNING] createpdf.py:377 Using image Images/lena.gif without specifying size.Calculating based on image size at 300dpi [near line 8 in file sample.rst]

これは画像に表示サイズを指定していないため発生します。画像は通常ピクセル等でサイズを表現しますが、PDF ではセンチやインチといったサイズで処理する必要があります。

rst2pdf にて reST ファイルを PDF に変換する場合 DPI(dots-per-inch) の値を利用して変換します。

300 ピクセルの画像を 300 DPI で変換すると、1 インチで表示されます。300ピクセルの画像を 100DPI で変換すると 3インチになります。

画像に以下のようにサイズを指定するのが一番良い方法です。

.. image:: Images/lena.png
   :width: 3in

実際の所、毎回画像のサイズを指定するのはなかなか難しいと思いますので、 WRNING が発生しても正常に画像が表示されるように DPI のデフォルト値を設定ファイルに記述して置くのが良いでしょう。

ディスプレイのサイズにもよりますが DPI は 72DPI か 94 DPI 程度にするとディスプレイで見ているサイズに近いサイズになるはずです。

rst2pdf の設定ファイルに以下を記述しておくと良いでしょう。

default_dpi=94

さらなる画像サポートの追加

PIL では多くのフォーマットをサポートしていますが、 PIL でサポートされない形式もあります。

PIL でサポートされない代表的なファイルとしては、Postscript、EPS、SVG等が存在します。

UniConvertor をインストールするとベクターイメージを PDF に埋め込むことができます。

curl -O http://sk1project.org/downloads/uniconvertor/v1.1.4/uniconvertor-1.1.4.tar.gz
tar xvfz uniconvertor-1.1.4.tar.gz
cd UniConvertor-1.1.4
sudo python setup.py install
mkdir ~/.uniconvertor

ベクターイメージを利用しないなら特に必要ありませんが、高品質な画像を PDF に埋め込みたい場合は必要になるでしょう。

ソースコードの色付け

.. code-block:: python

     def myFun(x,y):
         print x+y

を sample.rst に追記して変換すれば普通に変換されます。現状の rst2pdf は code-block ディレクティブにしか対応していません。

例えば sourcecode ディレクティブを利用している等他のディレクティブの場合、 createdpdf.py の 236 行目あたりに以下の追記すれば良いでしょう。

directives.register_directive('sourcecode', pygments_code_block_directive.code_block_directive)

色のスタイルを変更したい場合はやはりスタイルシート指定になります。

rst2pdf -s ja,emacs --font-path=/path/to/fonts sample.rst

の様にスタイルを複数指定するか、設定ファイルに複数スタイルを指定しておくことで可能になります。

stylesheets="ja,emacs"

ハイフネーション

そもそも hyphenation が何か良くわからない人もいるかもしれません。

hyphenation とは英文等で、一行の末尾で単語が切れる時が収まらない、ハイフンで区切って次の行に継続する処理のことです。

あまり日本語だと気にしないかもしれませんが、英文を PDF に変換する場合これをインストールしておかないと文書が読みずらくなります。

Wordaxe と PyHyphen が必要です。

easy_install でインストールするのが簡単です。

sudo easy_install -UZ wordaxe
sudo easy_install -UZ PyHyphen

ソースからインストールしたい場合は以下です。

curl -O http://pypi.python.org/packages/source/P/PyHyphen/PyHyphen-0.9.3.zip
unzip PyHyphen-0.9.3.zip
cd PyHyphen-0.9.3
sudo setup.py install

# http://sourceforge.net/projects/deco-cow/files/ から wordaxe-1.0.1.zip をダウンロード
unzip wordaxe-1.0.1.zip
cd wordaxe-1.0.1
sudo setup.py install