ドキュメンテーションを加速するストレスフリーの作図ツール『blockdiag』 jus2011年6月勉強会

日本UNIXユーザ会 2011年6月勉強会

Sphinx-users.jp
小宮健、清水川貴之

自己紹介：小宮健
Twitter: @tk0miya
 仕事
 (株)タイムインターメディア所属
 テクニカルオフィサ(技術責任者)として活動
 参加コミュニティ
 Sphinx-users.jp
 Python mini hack-a-thon
 Sphinx を中心にツールを開発
 blockdiag シリーズ
 Sphinx 拡張機能の開発
 sphinxcontrib-googlechart など
 rst2pdf (コミッタ)

ドキュメントとは?

 ドキュメント【document】
1. 資料的な文書。記録。
2. 記録映画。記録文学。
3. コンピューターで、プログラム開発の際に作る仕様書や使
用説明書。
(goo 辞書より)

ドキュメントとは?
 IT業界では設計書、手順書、利用マニュアルなどを指す
 設計書
 業務の全体像、経緯
 アーキテクチャやシステム間の連携
 システム構成、インフラ構成が把握できる
 手順書
 メンテナンス手順、作業手順
 利用マニュアル

 現代のシステムは複雑でマニュアルは必要不可欠なもの

システムは育つ
 システムは頻繁に形を変えていく
 機能、画面の追加
 システム増強
 ドキュメントはシステムの鏡
 システムの変更が反映されるべき

 だが、実際には反映されていないことが多い
 カラムが合わないテーブル定義
 足りない機能一覧
 削除されたページが載っている画面遷移図

もしドキュメントが無かったら…?
 ドキュメントが必要とされる場面
 新しいメンバーが参画するとき
 他のメンバーへの引き継ぎ時
 システムのトラブルが発生したとき

 もしこれらの場面でドキュメントが無かったら…?
 あとでドキュメントを作ると高いコストを支払うことになる

 いつでも手間をかけずに正確な情報へアクセスしたい

求められるドキュメントとは
 必要とされるドキュメントには三つの特徴がある

 内容が正確であること
 簡単に書けること
 誮もがいつでも参照・更新できること

 ドキュメントの内容が現在のシステムと一致している
 システムの変更内容が反映されている
 ドキュメントを読んでシステムを把握できる

 正確でないドキュメントは悪影響ばかり
 あなたは間違っているドキュメントを読みますか?

 ドキュメントに集中できる環境
 ツールによるアシスト
 テンプレートによる構成の再利用
 体裁や形式ではなく、書くべき内容に注力できるように

 書きづらいドキュメントはメンテナンスされない
 ドキュメントを書くのがイヤだと感じたことはありませんか?

 ドキュメントがメンバー全員に共有されている
 システムの知識を持った人が更新する
 新しい情報が分かったらなるべく早く更新する

 更新のタイミングを逃すとそのままになってしまう
 「あとで書こう」を忘れてしまったことはありませんか?
 「どこかにあったはず」と探し続けたことはありませんか?

求められるドキュメントとは
 必要とされるドキュメントの三つの特徴

 分厚いドキュメントの山では変化に対応できない
 必要なのはシンプルで変化に耐えうる軽量なドキュメント
 Lightweight Documentation
 ドキュメント作りを開発・運用サイクルに組み込む

Lightweight Documentation
 ツールの利用による効率的な更新
 見栄えより中身を重視
 更新できる規模、最低限の内容に押さえる
 すべてのメンバーが参照・更新できること
 自動抽出可能な情報はなるべく自動化する

 Lightweight Documentation を実現するツール
 各種 Wiki クローン
 Sphinx
 blockdiag シリーズ
 Javadoc

 これらのツールを組み合わせてサイクルを回す

まとめ
 ドキュメントは常に必要とされている
 システムの理解・把握や情報共有
 ドキュメント書いてますか?
 必要とされるドキュメント
 Lightweight Documentation
 ツールを組み合わせて、変化に対応する

blockdiag シリーズ
 ドキュメントには図がつきもの
 システム構成図
 画面遷移図
 フローチャート
 UML 系の図 (クラス図、シーケンス図など)
 ネットワーク図

 図を作るのはとても手間がかかってしまうもの
 = Lightweight ではない！

blockdiag シリーズ
 テキストを図に変換するツール群
 blockdiag：ブロック図、画面遷移図、フローチャート
 seqdiag：シーケンス図
 actdiag：アクティビティ図
 nwdiag：ネットワーク図

 blockdiag は定義ファイル(テキスト)から画像を生成する
 レイアウトは自動的に行われる
 多くの図形作成ツール(GUI ベース)と異なる考え方

blockdiag 定義の例
 変換元テキスト
{
トップページ -> ログイン -> マイページ;
トップページ -> 商品一覧 -> 商品詳細;
}

 変換後の画像

 blockdiag シリーズのキーワード
 メンテナンス性
 スピード感
 Enjoy

 Lightweight Documentation を支えるツールの一つ

 ドキュメンテーションツールとの連携
 Sphinx
 Redmine
 Trac
 moinmoin
 Mediawiki
 Web API

 既存のドキュメントに対して簡単に図を埋め込める

他のツールとの比較
 ブロック図やシーケンス図を作るときに利用するツール
 Excel, Visio
 Cacoo
 astah*
 PlantUML

 多くのツールは要素を自分で並べていく必要がある
 意図したとおりに要素を並べることができる
 変更の際は並べ替え作業がメインになる

追加/削除が大変

ここに 1 画面追加


１.スキマを作る


２.不要な矢印を消す


３.図形を配置する


４.矢印を調整

blockdiag のインストール
 blockdiag シリーズは easy_install コマンドでインストール
できます
 要：Python のインストール

% easy_install blockdiag
% easy_install seqdiag
% easy_install actdiag
% easy_install nwdiag

※一部環境では依存パッケージでハマることが多いので、
マニュアルをご覧下さい
(http://blockdiag.com/blockdiag-ja/build/html/introduction.html)

blockdiag による図の生成
 図を生成する際は blockdiag コマンドを実行する

% blockdiag sample.diag # → sample.png

定義ファイルの書き方 (blockdiag 編)
 blockdiag では「->」で要素を結びつけます

{
A -> B -> C;
}

 要素の背景色、形を変えることができます
{
A [color = red];
B [shape = diamond];
C [style = dotted];

A -> B -> C;
}

blockdiag で書けること (1)
 各要素ごとに色、画像、矢印の向きなどが設定できる
 背景色、線の色、実線/点線
 背景画像
 矢印の向き

 そのほかの装飾
 ノードのグルーピング
 遷移の説明文 (短め)

 ノードの shape 属性を指定する
 node1 [shape = “roundedbox”]
 基本系

 フローチャート系

 その他

 これらを組み合わせると複雑な図を書くことができます
 画面遷移図: http://bit.ly/lZkszJ
 ブロック図: http://bit.ly/kYpK6Y
 フローチャート: http://bit.ly/m7fLsM
 組織図: http://bit.ly/l6OOhZ

 seqdiag では「->」「=>」で要素を結びつけます

{
// 呼び出し + 戻り方向のシーケンス
A => B;

// 一方向のシーケンス
A -> B;
}

 ブロックを使うとネストしたシーケンスを記述できる

{
A => B {
// B がアクティブな間のシーケンス
B => C;
}
}

 これらを組み合わせると複雑な図を書くことができます。

 認証システムのシーケンス図： http://bit.ly/lwvEox

 actdiag と nwdiag もシンプルな書式で図を作成できる
 actdiag: http://bit.ly/kkcgIg
 nwdiag: http://bit.ly/kR5tYF

 詳細は blockdiag.com のマニュアルを参照して下さい

blockdiag の周辺ツール
 blockdiag の重要な周辺ツール「Interactive Shell」
 Web ブラウザを利用してリアルタイムに図を作れる
 SVG を利用しているため IE 非対応
 高速に情報を共有するのに向いている

 Interactive Shell を利用して、blockdiag をデモします

今後の展開
 Euro Python (6/20-6/26, イタリア) で LT 発表します
 新たな図、ドキュメントへの対応
 システム構成図
 ネットワーク図 (ラック、ハブ等の物理層)
 画面定義書
 他のツールと連携しての自動生成
 ネットワーク通信のシーケンス図
 ネットワーク図
 プログラム構成図

まとめ
 blockdiag シリーズを使って図を楽に書こう
 並び替えや位置調整に手間をかけない
 図を作るのにスピードを与える
 Sphinx や Trac, Wiki と組み合わせると便利

 楽するためにはもっと知恵と経験が必要
 意見やアイディアを集めてもっと楽したい

 URL: http://blockdiag.com/
 Twitter: #blockdiag
 Google グループ: blockdiag-discuss

自己紹介：清水川貴之
http://清水川.jp/ @shimizukawa
 仕事
 株式会社BeProud
 Djangoを使い始めました

 オープンソースコミュニティー活動:
 Sphinx-users.jp 副会長
 Zope/Plone 運営
 その他, pyspa系, XP系

 言語:
 C++/C/8086 -> Python/Rails

 書籍
 エキスパートPythonプログラミング(翻訳)
 アスキー・メディアワークス

イベントの紹介
 エキスパートPythonプログラミング読書会
 6/19(日) 明日です！
 場所: 大阪
 参加方法: ATND http://atnd.org/events/16731

 PyCon JP 2011
 8/27(土)
 場所: 東京
 参加方法: 7月に募集開始予定
 URL: http://2011.pycon.jp/

Sphinxとは何か

ドキュメントを作りたくなってしまう
魔法のツール

Sphinxとは何か

テキストエディタが
あれば編集可能

Sphinxとは何か

様々な出力
形式に対応

Sphinxとは何か

マニュアル作成から
サイト構築まで
応用しやすい

最近Sphinx利用者が増えています

JUS勉強会(2010/12/3)


Sphinx+翻訳Hack-a-thon(2011/2/12)


JUS勉強会(2011/6/18)

こんなところで使われています
 多くのOSSドキュメントやサイトで採用実績あり
 Python 2.6.2ドキュメント
 OpenPNE Web API仕様書
 groongaドキュメント…他多数

 テンプレート機能を用いてサイトを構成

こんなところで使われています

多くのドキュメントでの
利用実績多数！

 国内： http://sphinx-users.jp/example.html
 国外： http://sphinx.pocoo.org/examples.html

Sphinxの特徴

プレーンテキストなソースコード

Sphinxの特徴

プレーンテキストなソースコード

メモ帳でも
編集可能

Sphinxの特徴

ページ間の相互リンク

Sphinxの特徴

ページ間の相互リンク

ファイルリンク

用語リンク

Sphinxの特徴

強力なコードハイライト

実装言語とテンプレートとで200
前後の言語書式に対応
http://pygments.org/docs/lexers/

Sphinxの特徴

拡張機能で
さまざまなことができる

Sphinxの特徴

拡張機能で
さまざまなことができる

blockdiag拡張 UML描画

docx出力
HTML
テンプレート変更
Pythonコードから
数式描画
ドキュメント生成楽譜描画

Sphinxの特徴

ドキュメントは
100%日本語化されている

Sphinxの特徴

ドキュメントは
100%日本語化されている

リファレンスマニュアル以外にも
チュートリアルなどドキュメント多数！

ドキュメントを書くのに、何を使用しています
か？
 ワープロソフト
 Word
 一太郎
 OpenOffice Writer

MicrosoftのOfficeの
テンプレートのサイトより転載

か？
 表計算
 Excel
 Calc

MicrosoftのOfficeの
テンプレートのサイトより転載

か？
 プレゼンテーション
 PowerPoint
 KeyNote
 OpenOffice Impress

か？
 それ以外
 Wiki
 HTML手書き
 TeX

http://www.flickr.com/photos/boothy/26461481/ http://www.flickr.com/photos/omeyamapyonta/3052096
CC BY-NC by Dr Snafu 093/ CC BY-SA by PYONKO

Word Excel

Wiki Sphinx

http://www.flickr.com/photos/johncarleton/2367673332/ http://www.flickr.com/photos/stompy/11300916/ CC BY-
CC BY-NC-SA by John Carleton NC by Abizern

Word - pros

http://www.flickr.com/photos/jetalone/861945664/
CC BY by jetalone

Word - pros
 縦書きで編集できる
 文法チェックしてくれる
 差分比較機能がある
 参考文献、索引、
差し込み印刷etc…

CC BY by jetalone

Word - cons

CC BY by jetalone

Word - cons
 巨大な1ファイルになる
 探すのが大変
 複数人で編集が大変
 章の入れ替えとか厳しい

CC BY by jetalone

Excel - pros

http://www.flickr.com/photos/21183810@N00/43665
18191/ CC BY-NC-SA by Jerome Rothermund

Excel - pros
 Excel扱える人は多い
 ぱっと作るのは早くできる
 ロジカルシンキング的に苦心しなくても、罫線で武装する
と、見た目が立派に見える


Excel - cons


Excel - cons
 ワークシートで分断され、閲覧性が悪い
 内容の追加でレイアウトの修正が必要になると、修正に
膨大な時間がかかる


Wiki - pros

/ CC BY-NC-ND by milky.way

Wiki - pros
 圧倒的に柔軟
 構造化されていなくても、とりあえず入れておける
 複数人での編集・閲覧ができる


Wiki - cons


Wiki - cons
 文章の構成、質の維持に目を光らせる必要がある
 あるいは、Wikipediaのように構成を決めておく
 全体の構成を修正するのに手間がかかる
 トップダウン型ではないので、まとめて印刷や他形式に変
換がやりにくい


Sphinx - pros

86/ CC BY-SA by sweet_redbird

Sphinx - pros
 ドキュメントの背骨がしっかりさせる
 有機的に文章を繋げる仕組みを持っている
 説明ユニット
 プレーンテキスト。バージョンコントロールOK！


Sphinx - cons


Sphinx - cons
 背骨を気にして、コンテンツを追加する必要
 マークアップを覚える
 WYSIWIGではない


Sphinxのインストール(Linux, MacOS X)
 必要なもの
 Python, easy_install, Sphinxの3点セット
 パッケージ管理ツールを使えば一瞬
 Ubuntu
$ sudo apt-get install python-sphinx

 Mac OS X
$ sudo port install python-sphinx

Sphinxのインストール(Windows)
 必要なもの
 Python, easy_install, Sphinxの3点セット
 Python本体（python-2.7.2.msi）のインストール
 easy_install (distribute_setup.py) の取得とインストール

C:¥> python distribute_setup.py

 Sphinxのインストール
C:¥> easy_install sphinx

Demo

Sphinxのインストール(Windows)
 必要なもの
 Sphinxスタンドアロンインストーラのみ
 Sphinx-1.0.7.20110618-py2.7-win32.exe

これ一つでblockdiagシリーズも導入完了！

Demo

ただし、まだ実地検証が足りないため、みなさんのレポート
お待ちしております！

Sphinx拡張
 拡張をすることで様々な要求に対応できる
 新たな出力形式に対応したい
例: docx形式で出力したい

 マークアップを拡張したい
例: blockdiagを埋め込みたい

 HTMLテンプレートを追加したい

例: 業務向きなシンプルなのが欲しい

 デフォルトで組み込まれている拡張が多数！

組み込みのSphinx拡張
 autodoc – docstring からの読み込み
 intersphinx – 他のSphinxドキュメントへのリンク
 pngmath – 数式をPNG画像にレンダリング
 jsmath – JavaScriptを用いて数式をレンダリング
 graphviz – Graphvizのグラフを追加
 coverage – ドキュメントのカバレッジ状況の収集
 todo – Todoアイテムのサポート

他にも多くの組み込みSphinx拡張あり

サードパーティのSphinx拡張
 その他特筆すべき拡張
 blockdiagシリーズ
 ブロック遷移図を簡単な記述で作成！

 sdedit
 UMLでシーケンス図を描けます！

 sphinxjp.themes
 HTMLテーマをいくつか追加

 docxbuilder（開発中）
 SphinxでWordファイルを作成

blockdiag by @tk0miya
 ブロック遷移図を文字のみで書けます
 sphinxcontrib-blockdiag でSphinxでブロック遷移図を
書くことが可能

.. blockdiag::

diagram webapp {
login -> something -> logout -> login
}

sdedit (Quick Sequence Deiagram Editor)

 UML図をテキストから生成するツール

.. sequence-diagram::

:maxwidth: 500
:linewrap: false
:threadnumber: true

actor:Actor
sphinx:Sphinx[a]
dot:Graphviz
sdedit:Quick Sequence Diagram Editor

actor:sphinx.make html
sphinx:dot.render_diagram() ただし
sphinx:sdedit.render_diagram()
Javaのインストールが必要

sphinxjp.themes by @shimizukawa他
sphinx-users.jpスタイル

プレゼン表示(s6)

docxbuilder by @shimizukawa
 SphinxからWord形式で出力する拡張

現在開発中
です

Sphinxプロジェクトの作成（準備）
 “sphinx-quickstart”を使います
$ mkdir Unix-How-to
$ cd Unix-How-to
$ sphinx-quickstart

 とりあえずはEnterを連打！ ├── Makefile
├── _build
 conf.pyとディレクトリが作成 ├── _static
├── _templates
 この3つだけは回答する ├── conf.py
 プロジェクト名 ├── index.rst
└── make.bat
 バージョン番号
 著者名
Demo

reSTによるドキュメント作成（記述）
 reST = reStructuredText
 http://sphinx-users.jp/doc10/rest.html
Demo
============
 テキストでも見やすい形大見出し
============
 見出し
 コードブロック（ハイライト付き）中見出し
=========
 文書内／文書外リンク
小見出し
表
-------------

-リストアイテム1
 toctreeなどを作成する -リストアイテム2
#. 自動採番アイテム1

Sphinxによるドキュメントの生成（ビルド）

 自動作成されたMakefileをそのまま利用するだけ
$ make html

Demo
============
大見出し大見出し
============
中見出し
見出し
========= ・リストアイテム1
・リストアイテム2
-リストアイテム1 1. 自動採番アイテム1
-リストアイテム2 2. 自動採番アイテム2

応用例(1/2) 出力形式の変更
 HTML以外にもデフォルトでLaTeX、PDF 、ePubに
$ make latex
$ make latexpdf
$ make epub

 HTMLもデフォルトで複数のテーマを使用可

Demo

応用例(2/2) blockdiag拡張の利用
 インストール (スタンドアロン版なら導入済み)
C:¥> easy_install sphinxcontrib-blockdiag
Demo
 conf.pyの設定
extensions = []
extensions.append('sphinxcontrib.blockdiag')

blockdiag_fontpath = r'C:¥Windows¥Fonts¥msgothic.ttc'

 図の埋め込み記述
.. blockdiag::

{ A -> B -> C; }

テンプレートの作成
 テンプレートエンジン “Jinja2”を利用している

自分でテンプレートを作成することも可能
 大まかに分けて2つのhtmlを作成する
 ドキュメント全体の基礎 : layout.html
 各ページ : page.html

 デフォルトテーマ basic のテンプレート継承により時間が
削減

Sphinxドメイン
 ある言語を説明するマークアップとSphinx内のオブジェ
クトのリンク
 Python以外にも多くの言語に対応&独自に作成可能
(Erlang, Ruby, C++, JavaScript…)
 ドキュメント内で相互参照が可能
例) C
.. c:function:: int printf(const char *format, …)

Sphinx一問一答

Sphinxのアイコン怖いよ？

ホルスの目
このアイコンはSphinxの本家サイトで使用されているアイコ
ンで、「ホルスの目」と言います。エジプトではスフィンクスは
太陽の神ホルスの一面であると考えられています。

ホルスの目は1/2から1/64の分数を表す楔形文字で構成
されており、これを全部足すと63/64という1の近似に。
これが「ホルスの目分数」で、トト神が魔法で補って1になる
らしい。

「魔法のツールSphinx」
にふさわしいですね。

Sphinx一問一答

Wordのようなエディタは
ありますか？

Sphinx一問一答

Wordのドキュメントが
たくさんあるんですが、

Sphinxに変換する拡張は
ありますか？

Sphinx一問一答

PowerPointに
出力出来ますか？

Sphinx一問一答

○○をしたいときに
どう書けば良いか‥‥
逆引き辞典はありますか？

逆引き辞典

逆引き辞典、
出来ました (@r_rudi)

http://sphinx-users.jp/

Sphinx一問一答

皆さんの疑問・質問・要望を
教えてください！

Sphinxのコミュニティー
 Webサイト:
 http://sphinx-users.jp/
 メーリングリスト:
 http://sphinx-users.jp/mailinglist.html
 イベント:
 http://sphinx-users.jp/event/
 Twitter:
 #sphinxjp

ドキュメンテーションを加速するストレスフリーの作図ツール『blockdiag』 jus2011年6月勉強会

More Related Content

What's hot

Similar to ドキュメンテーションを加速するストレスフリーの作図ツール『blockdiag』 jus2011年6月勉強会

More from Takayuki Shimizukawa

Recently uploaded

ドキュメンテーションを加速するストレスフリーの作図ツール『blockdiag』 jus2011年6月勉強会