Sphinxでドキュメントを生成する（PDF編）

Sphinxは、HTMLだけではなく他の形式でも出力可能だ。今回はPDFを生成出来るようにしてみた。

Windowsでの導入方法については下記のエントリが詳しい。

• Sphinxでドキュメント生成-PDF（Windowsでの始め方） - torutkのブログ

今回はMacで試してみた。動作環境は下記の通り

• MacOS X 10.6.8
• Python 2.6 (MacPorts)
• Sphinx 1.0.7

rst2pdf

• 下記の手順に従ってrst2pdfをインストールして設定を行った。
  • rst2pdf拡張を使ったPDFファイル作成 — Python製ドキュメンテーションビルダー、Sphinxの日本ユーザ会

% sudo /opt/local/bin/easy_install-2.6 rst2pdf

• make pdfコマンドを叩いたら、下記のエラーが発生した。

[ERROR] styles.py:308 Error processing font VL-Gothic-Regular: too many values to unpack

• 下記の情報を参考にして、ja.jsonを変更。
  • rst2pdf でエラー – BmathLog
• 今度はPDFが正常に生成された。

% make pdf

画像ファイルも取り込まれているし、相互参照のリンクは有効だし、日本語の表示も問題ない。同じソースを使ってHTMLやPDFなど、異なる出力方法を選べるのは大変便利だ。

しかしながら、PDFの内容を確認してみると下記の問題が見つかった。

• blockdiagやseqdiagで作った図面がPDFに取り込まれない。これは下記のエントリで指摘されている内容と同じ症状だ。
  • Sphinxでドキュメント生成-図を描く（Windowsでの始め方） - torutkのブログ

writing Foo... [WARNING] basenodehandler.py:163 Unkn. node (self.elemdispatch): sphinxcontrib.blockdiag.blockdiag [near line UNKNOWN in file UNKNOWN]
[WARNING] basenodehandler.py:163 Unkn. node (self.elemdispatch): sphinxcontrib.seqdiag.seqdiag [near line UNKNOWN in file UNKNOWN]

• 日本語の箇条書きが折り返されない（下記はPDFの画面キャプチャ）。英語の箇条書だと折り返されるので（ハイフネーションの問題は有るけど）、日本語(CJK)特有の問題らしい。rst2pdfのIssueリストには関連する問題が上がっていた。

• • http://code.google.com/p/rst2pdf/issues/detail?id=405
  • http://code.google.com/p/rst2pdf/issues/detail?id=382

---

関連

• Sphinxでドキュメントを生成する - Basic