astah の画像を Sphinx に埋め込む拡張を作ってみた: sphinxcontrib-astah

先々週に cacoo の拡張をつくってそのあとパッケージングもしたのですが、
それに味をしめて(?) UML 系のツールとして名高い astah 向けの拡張もつくってみました。
sphinxcontrib-astah です。

やっていることは超シンプルで、内部で astah-command.sh を呼び出しているだけです。

この間 cacoo 向けの拡張をつくった時に気づいたのですが、
API やコマンド経由で画像を生成するツールで、
なおかつ画像のフォーマットが常に PNG や JPEG などのラスター形式のものについては、
sphinxcontrib-cacoo の実装がほぼそのまま使えるのではないかと思います。

astah 拡張を作るときは cacoo の API を呼び出している部分を
astah-command.sh の呼び出しに置き換えるぐらいの作業で対応することができました。

cacoo 拡張では次のことをしています。

image ディレクティブを拡張して cacoo-image ディレクティブを作成 (オプションも継承)
cacoo-image ディレクティブでは image ノードを cacoo_image ノードに置き換える (このとき、image ノードのオプションは引き継ぐ)
doctree-resolved イベントで cacoo_image ノードから画像を生成し、image ノードに置き換える

こうすることで、出力形式ごとの(HTML, LaTeX 用などの) visitor 関数を書く必要がなくなるため、
image ディレクティブ(や figure ディレクティブ)の豊富なオプションをサポートしつつ、
なおかつツールが生成した画像を読み込むことができるようになります。

もしドキュメントの出力に合わせて画像の形式を変更したいなどの要望が出てくると、
実装はもう少し面倒なことになりそうな気がします。
blockdiag や graphviz などでは、画像フォーマットを切り替えたり、
ベクタ形式の画像を生成したりと割と細かいことをしているのでこういった方法は使えないのですが、
新しいツールをサポートするときにお手軽に拡張を作るときは便利かもしれません。

こうしたサードパーティのツールを使う場合、テストを書くのが面倒なのが玉に瑕ですね。
mock を介したりしつつテストを書くと良いのでしょうが、
このふたつの拡張に関してはテストコードがない状態です。

テストがないコードに嫌悪感のある方、すっきりするチャンスです。
当方プルリクをお待ちしております:-)