1. ドキュメント、書いてますか？小宮 健 (@tk0miya)2011-02-19

2. おまえ誰よ？小宮 健 (@tk0miya)株式会社タイムインターメディア所属技術者募集中らしいですPython 歴は約 1年ぐらいSphinx-users の方から来ました15時ぎりぎりまで資料作ってました分かりづらかったらごめんなさい！

3. はじめにこのスライドの内容ドキュメント、書いてますか？Inside blockdiag (と仲間たち)資料はあとで会社のブログにアップしますhttp://labs.timedia.co.jp/“TIM Labs” で検索してください

4. ドキュメント、書いてますか?

5. 理想と現実ドキュメントは書くべき。実際のところは？ドキュメント書く時間がないコスト (リソース) がないそもそも開発が終わらない口伝でなりたっているプロジェクト= 一子相伝的プロジェクト

6. こんな子いるかな?「(納品しないから)今回はドキュメントなしで」「機能一覧に書いてない機能がたくさんある」「運用でカバーすることにしよう」「仕様書はあったら嬉しいなって」「ドキュメントなんて、あるわけない」「こんなの絶対おかしいよ」

7. 誰のためのドキュメント?納品物としてのドキュメントお客さんのもの設計/運用のためのドキュメント自分たちのものもしくは引き継ぐ誰かのためものもの大抵足りないのは設計/運用のためのドキュメントつまり困るのは自分たち！

8. 作ったはいいけれど…そのドキュメント、メンテナンスできてますか?合ってないテーブル定義足りない機能一覧キャプチャが古いマニュアル更新したいけどコスト/時間が足りないあとで泣くのは自分もしくは引き継ぐ羽目になった誰か書いて終わりではなく、メンテできる大きさが大事立派である必要はないドキュメントだって Lightweight 重要

9. Lightweight なドキュメントツールをうまく使うSphinx、Wiki で書くソースに埋め込む -> docstringを Sphinx などで抽出やり方を変えるテンプレートでショートカットするshimizukawaテンプレート @ Sphinx-users常に書き換える (Wiki 方式)無理なく、楽しく、続けられるドキュメントであること

10. ここまでのまとめ設計/運用のためのドキュメントを書こう書くだけじゃダメ、更新もしなくちゃ。無理なく、続けられる方法が必要Sphinx を使おうテンプレート化していこうExcel 方眼紙は止めようここのツールを作った

11. Inside blockdiag (と仲間たち)

12. blockdiagテキストから画面遷移図を生成するツールコマンドライン / Sphinx 拡張として動作悪名高きExcel 方眼紙がイヤで作った並べ替えるのが面倒、ずれる 、etc…

13. blockdiagの特徴定義ファイル(テキスト)から画像(PNG, SVG)を生成Graphvizっぽい文法 (DOT like 文法)自動的にレイアウトしてくれる追加/削除が簡単ずれたりしない日本語 (UTF-8) 対応easy_installblockdiagでインストール可能

14. blockdiag の使い方遷移図の定義を作りますdiagram { A -> B -> C; B -> D;}blockdiagコマンドで画像を生成% blockdiag –o sample.png input.diag

15. Inside blockdiagblockdiagは 4つのパートから構成されるパーサレイアウトエンジン描画エンジンノードレンダラー

16. Inside blockdiag：パーサDOT 文法 (graphviz由来) をまねた文法を採用diagram { A -> B -> C; B -> D;}テキストでもわかりやすい (like reST!)ノード間の関係や属性をわかりやすく表現できるfuncparserlibを利用してパーサを生成依頼して Python 2.4 でも動くようにしてもらった

17. Inside blockdiag：レイアウトエンジンレイアウトエンジンX 軸(横方向)、Y 軸(縦方向) の順に並べている説明が大変なので中身は割愛します自分がきれいだと思うようにレイアウト完全にヒューリスティック「見やすさ」は感覚的なもので正解はないイマイチなものを見かけたら教えて下さい

18. Inside blockdiag：描画エンジンblockdiagは PNG/SVG/PDF 形式で出力できるバックエンドには PIL/SVGdraw.py/reportlabを利用

19. Inside blockdiag：描画エンジンPIL っぽいインターフェースで中間層を作っているline, rectangle, arc, ellipse などの API がそろってる手がかかってる部分PIL で点線を書けるようにしたSVG でテキスト折り返し影のぼかし部分

20. Inside blockdiag：レンダラーノードの形状は差し替え可能になっているプラグインを書くことで形状を追加することができる

21. Inside blockdiag：レンダラー新しいシェイプを足す場合はプラグインを書く図形を書く、塗る、ラベルを配置する、接点を調整する図形の組み合わせで簡単に作れる来週あたりにプラグインの書き方を公開するつもり是非作って下さい

22. Inside blockdiag：周辺ツールInteractive shellデモツールとして大好評Appengine上で動いているフォームを書き換える度にリクエストしているAppengineでは PIL が動かないので SVG 出力してる問題点：blockdiagそのものだと勘違いされてる気がする

23. Inside blockdiag：周辺ツールWeb クローラーPycon mini JP のデモ用に作成デザイナーさんからキャプチャ画像で遷移図を作るという話を聞いたので作ってみたurllib + lxmlでスクレイプ + クローリング便利なクローラーライブラリを教えて下さいPyQtでキャプチャ取得 (by ransui先生)生成される図がでかすぎて閲覧不能デモ用と割り切って作り捨てることに。

24. Inside blockdiag：周辺ツールSphinx言わずもしれた便利なアイツSphinx 拡張を使うと reSTに直接埋め込むことができる.. blockdiag:: diagram { A -> B -> C; B -> D; }Sphinx との組み合わせは超便利 (らしい)

25. seqdiagテキストからシーケンス図を生成するツールコマンドライン / Sphinx 拡張として動作@shimizukawa師匠の指示で作らされた作った

26. ある日のできごとこのイラストは実在の団体とは関係ありませんSphinx のドキュメントにシーケンス図を埋め込みたいsdeditを使ったら? -> Java 入れるのイヤ。作って。なう。

27. blockdiag の使い方シーケンス図の定義を作りますdiagram { browser => server;}seqdiagコマンドで画像を生成% seqdiag –o sample.png input.diag

28. Inside seqdiagblockdiagコアを利用して 2時間でプロトタイプ作成1週間かけてちゃんと作り込んだ以降、絶賛放置中バグつぶしをしたら開発終了の予定シンプルに書いて、それっぽい図ができるBlockdiagと同じような周辺ツールがあるInteractive ShellSphinx 拡張

29. schema2rstDB スキーマから定義書を生成するForeign Key から ER 図っぽいものも生成できるサンプル以前作った schema2excel.rb を Sphinx 向けにリファインRails 風の DB Migration システムと相性がいい気がする作りながらスキーマを随時拡張していく

30. Inside schema2rstスキーマ情報の抽出Information_Schemaからごりごり SELECT してるだけMySQLでコメントを付けておくと表現がリッチに他の DBMS への対応はそのうち考えますER 図の生成dot ファイルを生成して Graphvizに渡してるテーブルが多すぎると図が大きくなって見づらい (体験談)面倒なので bitbucketで公開してるだけ

31. ここまでのまとめblockdiagは謎の技術で動いているわけじゃない普通の Python スクリプト素直なコードが多いので読みやすいはず但しレイアウトエンジンを除く要するに…Contributer募集。ブロック図とか UML とか好きな人ドキュメントを楽して書くために苦労できる人道のりが遠すぎて燃え尽きそうです。助けて

32. 次の目標ブロック図を作る機能構成とかシステム構成を表現する図http://twitter.com/#!/tk0miya/status/36083686684377088文書テンプレートの作成みんなが使ってるドキュメントからいいところを抽出いろんな人から意見を聞きたい！書くのが面倒くさくない / メンテするのにちょうどいい量@shimizukawaを巻き込んで、まとめていきます興味がある人は声かけてください

33. まとめドキュメントは楽して楽しく書こう自分のために。誰かのために書いて終わりではなく、メンテできる大きさが大事ツールややり方を工夫するとドキュメントは辛くないExcel 方眼紙はもはや化石Sphinx は冴えた一つのやり方もちろん blockdiag, seqdiagもね楽するためには知恵と経験が必要テンプレート、ツール群知識やアイディアください (@tk0miya まで)