torutkのブログ

ソフトウェア・エンジニアのブログ

Sphinxでドキュメント生成-図を描く（Windowsでの始め方）

コンピュータ

昨日までの日記の続きです。

プログラミングなどの技術情報を人に伝えるために文書を書くときは、日本語の文章主体だけでは効率よく伝達できないので、図・表、ソースコードを織り交ぜます。
Sphinxは、標準で表組み、ソースコードを文書に織り込むことができますが、肝心の図については直接の手段を持っていません。（整形テキストでキャラクタ文字を使った疑似図くらい）

ところが、Sphinxを調べていたところ、簡単に図を描くための拡張機能を作成・紹介しているページをいくつか見かけました。たぐっていくと、拡張機能の（多分）作者のブログに行き当たりました。以下です。

Sphinx + blockdiag で始めるドキュメント生活 @ yokohama.pm 2011/05 - TIM Labs

  • テキストで記述された図の論理情報を入力とし、図の画像ファイル（PNGまたはSVG）を出力するコマンド
  • コマンドは、ブロック図、UMLシーケンス図、UMLアクティビティ図、ネットワーク図の4種類
    • blockdiag, seqdiag, actdiag, nwdiag
  • Sphinxの拡張機能として組み込むと、Sphinxのソーステキストに図の論理情報を記述し、Sphinxが生成する文書（HTML）に図を織り込む
    • sphinxcontrib-blockdiag, sphinxcontrib-seqdiag, sphinxcontrib-actdiag, sphinxcontrib-nwdiag

４つのうち、ブロック図は汎用度が高く、技術的な思考表現を伝えるための様々な図を描くことができるので、ブロック図だけでも入れると相当文書作成環境がよくなります。

以下、Windows上に昨日までに整えたSphinx環境に4つのコマンドと4つのSphinx拡張機能とを追加する設定を記述します。

Windows上でSphinxに図（diag）の拡張を組み込む

依存関係のあるPythonモジュールを順次環境にインストールしていきます。先日同様、インターネット非接続環境へのインストールを考慮して、ひとつひとつダウンロードしてインストールする手順で示します。

Pythonのfuncparserlibモジュール

blockdiagが依存しているモジュールfuncparserlibをインストールします。

展開し、ディレクトリ内で　python setup.py install を実行します。

Pythonのwebcolorsモジュール（2011/07/18追記、2012/07/14更新）

blockdiagが依存しているモジュールwebcolorsをインストールします。

展開し、ディレクトリ内で　python setup.py install を実行します。

Pythonのordereddictモジュール（2011/11/26追記）

blockdiagが依存しているモジュールordereddictをインストールします。

展開し、ディレクトリ内で　python setup.py install を実行します。

PythonのPillowモジュール（2012/07/15追記）

blockdiagが依存しているモジュールPillowをインストールします。

easy_install Pillow-1.7.7-py2.6-win32.eggを実行します。

Pythonのblockdiagモジュール

図を描く基本機能（ブロック図作成の実体）のモジュールをインストールします。

展開し、ディレクトリ内で　python setup.py install を実行します。

Sphinxcontrib-blockdiag

ブロック図を作成するSphinx拡張モジュールをインストールします。

展開し、ディレクトリ内で　python setup.py install を実行します。

Pythonのseqdiagモジュール

シーケンス図を描く機能のモジュールをインストールします。

展開し、ディレクトリ内で　python setup.py install を実行します。

Sphinxcontrib-seqdiag

シーケンス図を作成するSphinx拡張モジュールをインストールします。

展開し、ディレクトリ内で　python setup.py install を実行します。

Pythonのactdiagモジュール

アクティビティ図を描く機能のモジュールをインストールします。

展開し、ディレクトリ内で　python setup.py install を実行します。

Sphinxcontrib-actdiag

ブロック図を作成するSphinx拡張モジュールをインストールします。

展開し、ディレクトリ内で　python setup.py install を実行します。

Pythonのnwdiagモジュール

ネットワーク図を描く機能のモジュールをインストールします。

展開し、ディレクトリ内で　python setup.py install を実行します。

Sphinxcontrib-nwdiag

ブロック図を作成するSphinx拡張モジュールをインストールします。

展開し、ディレクトリ内で　python setup.py install を実行します。

コマンドの単独実行

インストールしたコマンドを単独実行し、テキスト記述の情報から図を生成する確認をします。

blockdiagコマンドによるブロック図作成

テキストファイル(helloblock.diag)にブロック図の論理情報を記述します。日本語を使うときは、ファイルをUTF-8形式にします。

diagram {
  入力 -> 処理 -> 出力
}

コマンドで画像に変換します。

C:\work> blockdiag -f C:\Windows\Fonts\msmincho.ttc helloblock.diag

デフォルトではPNG形式のファイルhelloblock.pngが生成されます。-Tオプションで指定すればSVG形式を生成します。-fオプションでのフォント指定は日本語使用時に必要で、ASCII文字だけなら不要です。

seqdiagコマンドによるシーケンス図作成

テキストファイル(helloseq.diag)にシーケンス図の論理情報を記述します。

diagram {
  クライアント -> サーバー [label="要求"];
  クライアント <- サーバー [label="応答"];　
}

コマンドで画像ファイルに変換します。

C:\work> seqdiag -f C:\Windows\Fonts\msmincho.ttc helloseq.diag

コマンドのオプションは、blockdiagと同じです。

actdiagコマンドによるアクティビティ図作成

テキストファイル(helloact.diag)にアクティビティ図の論理情報を記述します。

diagram {
  新規 -> 担当 -> 解決 -> 終了;
  lane qa {
    label = QA担当;
    新規; 終了;
  }
  lane dev {
    label = 開発担当;
    担当; 解決;
  }
}

コマンドで画像に変換します。

C:\work> actdiag -f C:\Windows\Fonts\msmincho.ttc helloact.diag

コマンドのオプションは、blockdiagと同じです。

nwdiagコマンドによるネットワーク図作成

テキストファイル(hellonw.diag)にネットワーク図の論理情報を記述します。

diagram {
  network front {
    address = "192.168.1.0/24";
    server1 [address = "192.168.1.10"];
    server2 [address = "192.168.1.11"];
  }
  network back {
    address = "192.168.3.0/24";
    server1 [address = "192.168.3.10"];
    server2 [address = "192.168.3.11"];
  }
}

コマンドで画像に変換します。

C:\work> nwdiag -f C:\Windows\Fonts\msmincho.ttc hellonw.diag

コマンドのオプションは、blockdiagと同じです。

Sphinxドキュメントへの図の記述

conf.pyの修正

Sphinxのソーステキスト上に図の論理情報記述を行い、make時に画像生成するには、extensionsに拡張モジュールを追記します。
また、日本語を扱うときは、各モジュールに対してfontpath設定をします。アンチエイリアス表示とするには、各モジュールに対してantialiasをTrueに設定します。

extensions = ['sphinxcontrib.blockdiag', 'sphinxcontrib.actdiag', 'sphinxcontrib.seqdiag', 'sphinxcontrib.nwdiag']

blockdiag_fontpath = 'C:\Windows\Fonts\meiryo.ttc'
blockdiag_antialias = True
actdiag_fontpath = blockdiag_fontpath
actdiag_antialias = True
seqdiag_fontpath = blockdiag_fontpath
seqdiag_antialias = True
nwdiag_fontpath = blockdiag_fontpath
nwdiag_antialias = True
図の記載方法
.. blockdiag::

  diagram {
    ...（中略）
  }

.. seqdiag::

  diagram {
    ...（中略）
  }

.. actdiag::

  diagram {
    ...（中略）
  }

.. nwdiag::

  diagram {
    ...（中略）
  }
図のSphinx文書への織り込み
C:\work\hello> make html
  :

で、生成されるHTML文書に図の画像が貼られています。

PDFには図が反映されない？

rst2pdfでPDF生成を追加したSphinxにおいて、PDFへ生成させようとしましたが、

C:\work\hello> make pdf
  :

図は出ませんでした。コマンド実行途中に出るWARNINGが関係していそうですが。

writing HelloBlockDiagram... [WARNING] basenodehandler.py:163 Unkn. node (self.e
lemdispatch): sphinxcontrib.actdiag.actdiag [near line UNKNOWN in file UNKNOWN]
[WARNING] basenodehandler.py:163 Unkn. node (self.elemdispatch): sphinxcontrib.n
wdiag.nwdiag [near line UNKNOWN in file UNKNOWN]
[WARNING] basenodehandler.py:163 Unkn. node (self.elemdispatch): sphinxcontrib.s
eqdiag.seqdiag [near line UNKNOWN in file UNKNOWN]
[WARNING] basenodehandler.py:163 Unkn. node (self.elemdispatch): sphinxcontrib.b
lockdiag.blockdiag [near line UNKNOWN in file UNKNOWN]