Alligator Swamp

技術メモ

ドキュメントを作成するのが楽しくなるSphinxを使ってみた

Sphinxとは

ドキュメントを簡単に作成できるツール。
reStructuredText形式で記述しビルドすると作成完了。
因みにhtmlだけじゃなくてPDFとかePub形式でも出力できる模様。
pythonで作成されているが、使うだけならpの字も知らなくて大丈夫。
pも知らない私が言うので間違いない(キリッ

使用してみた

f:id:waniji:20120504235934p:plain
こんな感じで記述したテキストをビルドすると。
f:id:waniji:20120504235953p:plain
こうなる。
WordとかExcelだと複数ファイル or 複数シートにまたがって見辛い+管理しづらいことこの上ない。
HTMLを直にいじらなくていいので、書きやすく差分も取り易い。
うん、なかなか便利ですね。

便利な拡張機能blockdiag

個人的にはこの拡張機能Sphinxの魅力を格段に上げていると思う。
いつもはExcelとかVisioとかで書いているブロック図とかアクティビティ図をテキスト形式で作成できる。
f:id:waniji:20120505000128p:plain
これが。
f:id:waniji:20120505000134p:plain
こんな図に。
自由度は無くなりますが、微調整する時のイライラ感は軽減されるはず。
どんな図になるか気になって何回もビルドする方は、「Interactive shell for blockdiag」を使うと幸せになれます。
リアルタイムで図を表示してくれる優れもの。

-------------------------------
Interactive shell for blockdiag
http://blockdiag.appspot.com/
-------------------------------

気になる点

・新しいものは何でもそうですけど、最初は学習するコストがかかりますね。導入しようとしてもチームメンバーから拒否反応が結構出そう。

・テキストを変更すると毎回ビルドする必要があるので、そこが結構面倒くさい。omakeを使えば自動ビルドしてくれるのでまぁ問題はないかも。

・大規模な構成図とか作成するのは流石に厳しい?

まとめ

正直Excelのシートが複数あると見る気も無くすので、簡単に作成出来てブラウザで見れるのは素晴らしいと思います。

インストール方法

※Windowsの場合
1.pythonインストール
2.easy_installのインストール
3.sphinxのインストール
簡単なプロジェクトを作ってみたければ、以下も実行。
4.sphinx-quickstartを実行

インストールからプロジェクト作成などの方法は、Sphinxの日本ユーザ会の方々がわかり易く纏められているので、以下URLを参照されたし。
http://sphinx-users.jp/gettingstarted/index.html

参考にさせて頂いたWebサイト・スライドなど

Sphinx Overview(日本語訳)
http://sphinx.shibu.jp/

Sphinx-Users.jp
http://sphinx-users.jp/

ブロック図生成ツール blockdiag
http://blockdiag.com/ja/

手軽にメンテナンスできるドキュメントのヒミツ
http://www.slideshare.net/TakeshiKomiya/blockdiag-201107-odstudy