Sphinx + blockdiag + seqdiag + nwdiag + actdiag でドキュメント書いて日本語PDFへ出力したメモ

Sphinxのインストール

Macであればhomebrewでインストールできますが、残念ながらそのままではPDF形式で書き出す時に日本語が使えません。既にインストール済みの場合はパッチを当てる事もできますが、ここはパッチ済みのものをインストールします。

なお、ここで使っている"easy_install"コマンドはPythonのパッケージ管理スクリプトです。MacOSXであればはじめからPythonが入っていますので、このコマンドは特に何もしなくても使えるはずです。

   $ easy_install https://bitbucket.org/sphinxjp/website/downloads/Sphinx-1.1.2sphinxjp-latex.tar.gz

Latexのインストール

Ubuntu Linux
aptで入れられます。なんか色々インストールしてようやく日本語PDF出力できるようになりました。
無駄な事もしてるかもしれませんが、とりあえずやったことまるっと書いておきます。

  $ sudo apt-get install texlive texlive-base texlive-latex3 \
                         platex-bin okumura-clsfiles ptex-base \
                         ptex-bin dvipsk-ja xdvik-ja ptex-jisfonts \
                         gs-cjk-resource jmpost dvipdfmx \
                         texlive-math-extra okumura-clsfiles \
                         jbibtex-bin mendexk
  $ sudo apt-get install texlive-latex-extra nkf dvipng
  $ sudo apt-add-repository ppa:texlive-backports/ppa
  $ sudo apt-get update
  $ sudo apt-get install texlive-lang-cjk
  $ sudo apt-get install xdvik-ja
  $ sudo apt-get install texlive-latex-extra
  $ sudo apt-get install texlive-fonts-recommended
  $ sudo apt-get install ttf-sazanami-gothic ttf-sazanami-mincho

MacOSX
Sphinxをインストールすれば、既にHTML等への書き出しはできますが、PDFに書き出すにはLatexが必要です。

MacではTexLive( http://www.tug.org/mactex/2011/ )をインストールすればLatexと各種付属コマンドが使えるようになります。

また、MacでのTexliveのインストール方法や各種設定は
Mac-Tex Wiki 奥村研究所
が詳しいです。

ここではTexLive-2011のトップページから最新のMacTexをダウンロードしてインストールします。

ダウンロードページ http://www.tug.org/mactex/2011/

blockdiagのインストール

blockdiagはブロック図生成ツールでSphinxと連携する事ができます。
blockdiagのインストールはeasy_installから行えます。

   # easy_install blockdiag

更にSphinxのblockdiag拡張をインストールします。

   # easy_install sphinxcontrib-blockdiag

seqdiagのインストール

seqdiagはシーケンス図生成ツールでSphinxと連携する事ができます。
seqdiagのインストールはeasy_installから行えます。

   # easy_install seqdiag

更にSphinxのseqdiag拡張をインストールします。

   # easy_install sphinxcontrib-seqdiag

nwdiagのインストール

nwdiagはネットワーク図生成ツールでSphinxと連携する事ができます。

nwdiagのインストールはeasy_installから行えます。

   # easy_install nwdiag

更にSphinxのnwdiag拡張をインストールします。

   # easy_install sphinxcontrib-nwdiag

また、シスコルータのアイコンを使用する為の拡張をインストールします

   # easy_install blockdiagcontrib-cisco

利用出来るアイコンは `シスコアイコン一覧を参照してください。

追記

私のMacOSX環境ではシスコルータを使おうとすると"decoder jpeg not available"というエラーがでて使えませんでした。回避するには一旦PILを削除して入れ直します。

   # brew install libjpeg (既に存在するというメッセージが出る事を確認)
   # mv /Library/Python/2.7/site-packages/PIL-1.1.7-py2.7-macosx-10.7-intel.egg /tmp/
   # easy_install pil

actdiagのインストール
nwdiagはネットワーク図生成ツールでSphinxと連携する事ができます。

nwdiagのインストールはeasy_installから行えます。

   # easy_install actdiag

更にSphinxのactdiag拡張をインストールします。

   # easy_install sphinxcontrib-actdiag

以上でセットアップ完了。

sphinx-quickstartによるプロジェクト生成

プロジェクトの生成はコマンドで行います。

   $ sphinx-quickstart

いくつか質問されます。絶対に回答しなければならないのは、次の項目です。後はEnterキーだけで大丈夫です。

プロジェクト名
バージョン番号
著者の名前

プロジェクトの初期設定

日本語PDFを書き出し、さらにblockdiag等によるダイアグラム拡張を有効にするにはプロジェクト毎に以下の設定を行う必要があります。

プロジェクトディレクトリの直下にあるconf.pyを編集します。

   # 言語の設定(既にあるので変更)
   language = 'ja'
   
   # LaTeX の docclass 設定(新規で追加)
   latex_docclass = {'manual': 'jsbook'}
   
   # Enabled extensions(既にあるのでblockdiag,seqdiag,nwdiag拡張を追加)
   extensions = ['sphinxcontrib.blockdiag', 'sphinxcontrib.seqdiag', 'sphinxcontrib.nwdiag', 'sphinxcontrib.actdiag']

   # Fontpath for blockdiag (truetype font) (新規追加する)

   # Mac OSXでOsakaフォントを使う場合
   blockdiag_fontpath = '/Library/Fonts/Osaka.ttf'

   # Ubuntu Linuxでsazanami-minhchoを使う場合
   blockdiag_fontpath = '/usr/share/fonts/truetype/sazanami/sazanami-mincho.ttf'

   # 以下共通
   blockdiag_antialias = True
   seqdiag_fontpath = blockdiag_fontpath
   seqdiag_antialias = True
   nwdiag_fontpath = blockdiag_fontpath
   nwdiag_antialias = True
   actdiag_fontpath = blockdiag_fontpath
   actdiag_antialias = True