Sphinx で日本語を含む PDF 出力をする

PDF を納める必要があったのでやった。Sphinx というか reST での日本語出力には若干の難があるらしい。けど、これも先人のとおりにやったら簡単にできた。

rst2pdf 方式

(8日目) Sphinx から PDF を生成してみよう (rst2pdf 編) - Hack like a rolling stone をまず参考にやってみた。pip install rst2pdf, PIL 環境構築, VLゴシックのようなフォントをいれる。 ja.json を作成して読み込ませる。PIL 環境の構築はハマりやすいから http://atasatamatara.hatenablog.jp/entry/20120803/1344001904 を参考にするといい。

結果としてはうまくいかなかった。後述の日本語のなんらかのパッチのはいった Sphinx だったらできたかもしれないけど、一部が文字化けした。あと、後述の latex 経由のほうが印刷物としてのオプションが豊富でいい感じだった。

LaTeX 経由で PDF 出力

(11日目) Sphinx から PDF を生成してみよう (LaTeX 編) - Hack like a rolling stone と LaTeX経由でのPDF作成 :: ドキュメンテーションツール スフィンクス Sphinx-users.jp を参考にした。

TeX 環境の構築

Mac なので MacTeX を導入した。若干重い。Linux なら LiveTex2011 あたりとからしい。Windwosはよくわからないけど、それっぽいのがあるらしい。

インストールしたらアップデートも必要。これもわりと時間がかかる。

sudo tlmgr update --self
sudo tlmgr update --all

TeX 関係の PATH を通す

そのまま。上記の記事だと2011年で若干違ったりするから、適宜置き換え。今回は2012年だった。

export PATH=$PATH:/usr/local/texlive/2012/bin/universal-darwin

Sphinx PDF 出力日本語パッチ済みのものをダウンロードする

ありがたや

pip uninstall Sphinx
pip install https://bitbucket.org/sphinxjp/website/downloads/Sphinx-1.1.3sphinxjp-latex.tar.gz

Sphinx の conf.py の設定

以下を設定する

# 言語の設定
language = 'ja'
# LaTeX の docclass 設定
latex_docclass = {'manual': 'jsbook'}

build!

make latexpfja

これで _build/latex/ 以下にPDFが出力される

継続的ビルド

Sphinx のビルドをファイル監視して自動で行う と同じ要領でファイル更新のたびにプレビュー

watchmedo shell-command --patterns="*.rst" --recursive --command='make latexpdfja'

とてもよい

LaTeX のオプション

印刷物としてそれっぽくいいかんじに出力するためには ビルド設定ファイル(conf.py) — Sphinx 1.1 (hg) documentation を参考にするといい。ページの改行とか、脚注とか、そういうオプションが豊富にあるので適宜設定する。

まあ

かなしみの Word や Excel 仕様書じゃなくて Sphinx によるよろこびの仕様書、よい。あと、仕様書もHTMLで十分じゃんと思ってたけど、なんかこう綺麗なPDFってちょっとうれしい感ある。