読者です 読者をやめる 読者になる 読者になる

(11日目) Sphinx から PDF を生成してみよう (LaTeX 編)

今日のアドベントカレンダーは再び PDF 生成の話です。

前回は rst2pdf を使って PDF 生成を行いましたが、今日は LaTeX 経由で PDF 生成する方法を紹介します。
どちらも PDF 形式のドキュメントを生成することができますが、
それぞれで使い方や仕上がりが異なっているので、どちらかお好きな方で試すのがよいと思います。

TeXLive 2011 のインストール

まずは LaTeX をインストールします。
Sphinx では日本語の文字コードとして UTF-8 を利用しているため、
利用する LaTeXUTF-8 に対応したものである必要があります。

ここでは TeX 系統合パッケージのひとつである TeXLive を利用します。
なお、TeXLive 2009 までは収録されている pLaTeX は EUC-JP ベースとのことなので、
ここでは最新版の 2011 を利用するようにします。

Debian に収録されている TeXLive は 2009 なので、TeXLive のインストーラを利用してインストールします。*1

$ wget http://mirror.ctan.org/systems/texlive/tlnet/install-tl-unx.tar.gz
$ tar xzvf install-tl-unx.tar.gz
$ cd install-tl-20111210
$ sudo ./install-tl
Loading http://ftp.jaist.ac.jp/pub/CTAN/systems/texlive/tlnet/tlpkg/texlive.tlpdb
Installing TeX Live 2011 from: http://ftp.jaist.ac.jp/pub/CTAN/systems/texlive/tlnet
Platform: i386-linux => 'Intel x86 with GNU/Linux'
Distribution: net  (downloading)
Using URL: http://ftp.jaist.ac.jp/pub/CTAN/systems/texlive/tlnet
Directory for temporary files: /tmp

======================> TeX Live installation procedure <=====================

=======> Note: Letters/digits in <angle brackets> indicate menu items <=======
=======>       for commands or configurable options                   <=======

 Detected platform: Intel x86 with GNU/Linux

 <B> platforms: 1 out of 19

 <S> installation scheme (scheme-full)
     84 collections out of 85, disk space required: 2932 MB

 Customizing installation scheme:
   <C> standard collections
   <L> language collections

 <D> directories:
   TEXDIR (the main TeX directory):
     /usr/local/texlive/2011
   TEXMFLOCAL (directory for site-wide local files):
     /usr/local/texlive/texmf-local
   TEXMFSYSVAR (directory for variable and automatically generated data):
     /usr/local/texlive/2011/texmf-var
   TEXMFSYSCONFIG (directory for local config):
     /usr/local/texlive/2011/texmf-config
   TEXMFVAR (personal directory for variable and automatically generated data):
     ~/.texlive2011/texmf-var
   TEXMFCONFIG (personal directory for local config):
     ~/.texlive2011/texmf-config
   TEXMFHOME (directory for user-specific files):
     ~/texmf

 <O> options:
   [ ] use letter size instead of A4 by default
   [X] allow execution of restricted list of programs via \write18
   [X] create all format files
   [X] install macro/font doc tree
   [X] install macro/font source tree

 <V> set up for portable installation

Actions:
 <I> start installation to hard disk
 <H> help
 <Q> quit

Enter command: i

"Enter command" が表示されたら I と入力してお茶を淹れにいきましょう。
TeXLive は TeX 関係のパッケージが大量に収録されている超巨大パッケージで、
約 2GB ほどのファイル群をダウンロードします。


アップデートが完了した後、TeXLive のコマンドがどこからでも利用できるよう、
環境変数 PATH に /usr/local/texlive/2011/bin/i386-linux を追加してください。

なお、TeXLive は定期的に構成パッケージの更新が行われているので、
定期的に以下のコマンドでアップデートを行なってください。

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

Sphinx の更新

現在の最新版である Sphinx 1.1.2 は日本語 TeX の出力に問題があり、
手順どおりに進めても日本語が含まれているとうまくビルドすることができません。

この問題に対して、現在打田さんの手によって日本語 LaTeX 周りの改良が進められています。
これらの改良はまとまり次第 Sphinx 本体に反映されることになると思いますが、
現時点では手動で Sphinx に修正を入れる必要があります。


修正はパッチとして提供されていないため、1ファイルずつ差し替えを行いました。

$ cd /usr/local/lib/python2.6/dist-packages/Sphinx-1.1.2-py2.6.egg/sphinx
$ sudo mv quickstart.py quickstart.py.orig
$ sudo wget https://bitbucket.org/uchida/sphinx/raw/f5de3b205a52/sphinx/quickstart.py
$ cd texinputs
$ sudo mv Makefile Makefile.orig
$ sudo mv fncychap.sty fncychap.sty.orig
$ sudo mv sphinx.sty sphinx.sty.orig
$ sudo wget https://bitbucket.org/uchida/sphinx/raw/f5de3b205a52/sphinx/texinputs/Makefile
$ sudo wget https://bitbucket.org/uchida/sphinx/raw/f5de3b205a52/sphinx/texinputs/fncychap.sty
$ sudo wget https://bitbucket.org/uchida/sphinx/raw/f5de3b205a52/sphinx/texinputs/sphinx.sty
$ cd ../writers
$ sudo mv latex.py latex.py.orig
$ sudo wget https://bitbucket.org/uchida/sphinx/raw/f5de3b205a52/sphinx/writers/latex.py

LaTeX 経由で PDF ファイルを生成する

では、Sphinx から PDF ファイルを出力してみましょう。

Sphinx プロジェクトの設定として、conf.py に以下の行を追加します。

# 言語の設定
language = 'ja'

# LaTeX の docclass 設定
latex_docclass = {'manual': 'jsbook'}

そして、以下のコマンドで PDF の生成を行います。

$ make latex
$ make -C _build/latex all-pdf-ja

生成された PDF はこんな形式になります。rst2pdf で生成されたものと見比べてみてください。



なお、打田さんの修正を適用してから Sphinx プロジェクトを作成した場合は
latexpdfja という make ターゲットが用意されているので

$ make latexpdfja

というコマンドだけで PDF を生成することができます。


以前はかなり LaTeX と格闘しながらビルドしていた印象があるのですが、
TeXLive 2011 を利用し、打田さんのまとめられた修正を適用することで
とても簡単に PDF 出力ができるようになっています。

ディストリビューションで TeXLive 2011 が利用されるようになることと、
修正が Sphinx 本体に取り込まれるともっともっとかんたんに使うことが出来るようになるでしょう。
その日が待ち遠しですね :-)

*1:ディストリビューションの対応状況は[http://code.google.com/p/python-doc-ja/wiki/LaTeXBuild:title=こちらのページ]から確認できます…が、VineLinux 以外は対応していないようです