ドキュメンテーションを加速するストレスフリーの作図ツール『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月勉強会

Recommended

Recommended

More Related Content

What's hot

What's hot (20)

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

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

More from Takayuki Shimizukawa

More from Takayuki Shimizukawa (20)

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