Sphinxで素早く簡単に綺麗な日本語のPDFを作成する方法 – (DxD)∞

ドキュメントを書くのが楽しくなるPython製ドキュメント作成ツール「Sphinx」で簡単にPDFを作成する方法を紹介します。

Sphinxは1つのテキストファイルからHTMLやPDF、ePub等々をあっという間に生成してくれる素敵なツールです。

SphinxでPDFを生成する方法としては、「SphinxでPDFファイル作成」や「Sphinx & blockdiag Advent Calendar(全部俺) : ATND」の「(8日目) Sphinx から PDF を生成してみよう (rst2pdf 編)」「(11日目) Sphinx から PDF を生成してみよう (LaTeX 編)」で「rst2pdf」や「LaTeX」を使用する方法が紹介されているのですが、実際に試してみると周辺ツールの導入が大変だったり、エラーが出たりでなかなか思うようにPDFを作成できませんでした。

そこで発想を変えて、SphinxでHTMLを作成し、そのHTMLからPDFを生成する方法を試してみたところ、おおよそ実用的なPDFが生成できることがわかりました。以下、今回試してみた方法の(Ubuntuでの)手順です。

wkhtmltopdfを導入

まず、「wkhtmltopdf」を導入します。wkhtmltopdfはWebKitを利用して、HTMLをPDFに変換してくれるツールです。

プロジェクトのダウンロードページから最新の開発版(現時点では「wkhtmltopdf-0.11.0_rc1 Linux Static Binary」)をダウンロードしてインストールします。

apt-getコマンドでもインストールできますが、Qtにパッチを当てないと使えない機能が多く、PDFの生成時に細かい制御が行えません。「Static Binary」にはパッチ済みのQtが含まれています。

wget http://wkhtmltopdf.googlecode.com/files/wkhtmltopdf-0.11.0_rc1-static-i386.tar.bz2tar xvf wkhtmltopdf-0.11.0_rc1-static-i386.tar.bz2

アーカイブを展開してできた「wkhtmltopdf-i386」をパスの通った場所に置いておきます。

SphinxでHTMLをビルド

Sphinxのドキュメントは、必要に応じて「onlyディレクティブ」や「ifconfig拡張」を使用してコンテンツを切り替えるようにしておきます。

PDFに変換するHTMLをSphinxでビルドします。今回は、複数のドキュメントから1つのHTMLファイルを生成してくれる「singlehtml」ビルダーを使用しました。

make singlehtml

PDF用のCSSを定義

PDF用のユーザースタイルシートを作成します。

Sphinxのテーマに印刷用スタイルシートがある場合はそれを利用することもできます。その場合はこの節の作業は不要です。

vi pdf.css

HTMLをwkhtmltopdfでそのまま変換するとHTML要素の途中で改ページされてしまいます。CSSの「page-break-inside」プロパティを利用して改ページの可否を定義します。

その他、必要に応じて「page-break-inside」「page-break-before」「page-break-after」プロパティを利用して改ページや細かいスタイルを定義します。

html, body { background-color: white !important; }div.bodywrapper { margin: 0 !important; border-left: none !important; }div.related,div.footer,div.sphinxsidebar,div.body a.headerlink { display: none !important; }div.body * { page-break-inside: avoid !important; }div.body span[id^="document-"] ~ span[id^="document-"] ~ div.section h2 { page-break-before: always !important; }div.body h3, div.body h4, div.body h5, div.body h6 { page-break-after: avoid !important; }div.body h3 + *, div.body h4 + *, div.body h5 + *, div.body h6 + * { page-break-before: avoid !important; }div.body p.rubric { page-break-after: avoid !important; }div.body p.rubric + * { page-break-before: avoid !important; }/* その他色々 ... */

wkhtmltopdfでHTMLをPDFに変換

作成したユーザースタイルシートを指定して、SphinxでビルドしたHTMLファイルをPDFファイルに変換します。

wkhtmltopdf-i386 --user-style-sheet pdf.css _build/singlehtml/index.html index.pdf

変換が完了すると目次や内部・外部リンクの付いたPDFが生成されます。

印刷用スタイルシートを利用する場合

Sphinxテーマの印刷用スタイルシート(メディアタイプが「print」のもの)を利用する場合は、wkhtmltopdに「–print-media-type」オプションを付けて実行します。

wkhtmltopdf-i386 --print-media-type _build/singlehtml/index.html index.pdf

まとめ

wkhtmltopdfはWebKitを利用しているのでCSS3やJavaScriptも普通に使えますし、「wkhtmltopdf 0.10.0 rc2 Manual」にある各種オプションを使用することで生成するPDFもかなり細やかに制御できます。

Sphinxのテーマでコンテンツやデザインを切り替えることもできますし、blockdiag等の拡張も反映されます (ただし、自分の環境ではblockdiagを含むドキュメントをsiglehtmlビルダーでビルドするとFile "/usr/local/lib/python2.7/dist-packages/docutils-0.8.1-py2.7.egg/docutils/nodes.py", line 534, in __getitem__ return self.attributes[key]というエラーが出てビルド自体ができませんでした)。

rst2pdfやLaTeX経由のPDF生成は試せなかったので詳しくはわからないのですが、両者の良いとこ取りをしつつ、普通のHTMLドキュメントを作成する感覚でPDFが生成できるのは嬉しいのではないでしょうか?Sphinxで素早く簡単に綺麗な日本語のPDFを作成したい場合にはぜひ一度お試しください。

広告

コメントを残す

以下に詳細を記入するか、アイコンをクリックしてログインしてください。

WordPress.com ロゴ

WordPress.com アカウントを使ってコメントしています。 ログアウト / 変更 )

Twitter 画像

Twitter アカウントを使ってコメントしています。 ログアウト / 変更 )

Facebook の写真

Facebook アカウントを使ってコメントしています。 ログアウト / 変更 )

Google+ フォト

Google+ アカウントを使ってコメントしています。 ログアウト / 変更 )

%s と連携中