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

Ad

Ad

Ad

Ad

Ad

Ad

Ad

Ad

Ad

Ad

Ad

Ad

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

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

自己紹介：小宮健
Twitter: @tk0miya
 仕事
 (株)タイムインターメディア所属
 テクニカルオフィサ(技術責任者)として活動
 参加コ...

ドキュメントとは?

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

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

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

 だが、実際には反映されていないことが多い
 カラムが...

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

 もしこれらの場面でドキュメントが無かったら…...

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

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

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

 正確でないドキュメントは悪影響ばかり
 あなたは間違っているドキュメ...

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

 書きづらいドキュメントはメンテナンスされない
 ...

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

 更新のタイミングを逃すとそのままになってしまう
 「あとで...

求められるドキュメントとは
 必要とされるドキュメントの三つの特徴
 内容が正確であること
 簡単に書けること
 誮もがいつでも参照・更新できること

 分厚いドキュメントの山では変化に対応できない
 必要なのはシンプ...

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

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

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

まとめ
 ドキュメントは常に必要とされている
 システムの理解・把握や情報共有
 ドキュメント書いてますか?
 必要とされるドキュメント
 内容が正確であること
 簡単に書けること
 誮もがいつでも参...

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

 図を作るのはと...

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

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
...

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

% blockdiag sample.diag # → sample.png

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

{
A -> B -> C;
}

定義ファイルの書き方 (blockdiag 編)
 要素の背景色、形を変えることができます
{
A [color = red];
B [shape = diamond];
C [style = dott...

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

blockdiag で書けること (2)
 そのほかの装飾
 ノードのグルーピング
 遷移の説明文 (短め)

blockdiag で書けること (3)
 ノードの shape 属性を指定する
 node1 [shape = “roundedbox”]
 基本系

blockdiag で書けること (4)
 ノードの shape 属性を指定する
 node1 [shape = “roundedbox”]
 フローチャート系

blockdiag で書けること (5)
 ノードの shape 属性を指定する
 node1 [shape = “roundedbox”]
 その他

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

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

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

// 一方向のシーケンス
...

定義ファイルの書き方 (blockdiag 編)
 ブロックを使うとネストしたシーケンスを記述できる

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

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

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

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

 詳細は blockdiag...

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

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

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

 楽するためにはもっと知...

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

 オープンソースコミュニティー活動:
 Sphinx-users.jp...

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

 PyCon JP 201...

Sphinxとは何か

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

Sphinxとは何か

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

Sphinxとは何か

様々な出力
形式に対応

Sphinxとは何か

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

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

JUS勉強会(2010/12/3)

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

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

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

JUS勉強会(2011/6/18)

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

 テンプレート機能を...

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

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

 国内： http://sphinx-users.jp/example.html
 国外： http://sphinx.poco...

Sphinxの特徴

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

Sphinxの特徴

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

メモ帳でも
編集可能

Sphinxの特徴

ページ間の相互リンク

Sphinxの特徴

ページ間の相互リンク

ファイルリンク

用語リンク

Sphinxの特徴

強力なコードハイライト

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

Sphinxの特徴

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

Sphinxの特徴

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

blockdiag拡張 UML描画

docx出力
HTML
テンプレート...

Sphinxの特徴

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

Sphinxの特徴

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

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

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

...

ドキュメントを書くのに、何を使用しています
か？
 表計算
 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 ...

Word - pros

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

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

http://www.flickr....

Word - cons

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

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

http://www.flickr.com/photos/je...

Excel - pros

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

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

http://www.flic...

Excel - cons

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

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

http://www.flickr.com/photos/...

Wiki - pros

http://www.flickr.com/photos/7506006@N07/1197395511
/ CC BY-NC-ND by milky.way

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

http://www.flickr.com/photos/7506006@...

Wiki - cons

http://www.flickr.com/photos/7506006@N07/1197395511
/ CC BY-NC-ND by milky.way

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

Sphinx - pros

http://www.flickr.com/photos/18261299@N00/44724083
86/ CC BY-SA by sweet...

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

http://...

Sphinx - cons

http://www.flickr.com/photos/18261299@N00/44724083
86/ CC BY-SA by sweet...

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

http://www.flickr.com/photos/1826129...

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

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

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

これ一つでblockdiag...

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

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

 HTMLテンプレートを追...

組み込みのSphinx拡張
 autodoc – docstring からの読み込み
 intersphinx – 他のSphinxドキュメントへのリンク
 pngmath – 数式をPNG画像にレンダリング
 jsmath – Jav...

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

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

 sphinxjp...

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

.. blockdiag::

...

sdedit (Quick Sequence Deiagram Editor)

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

.. sequence-diagram::

:maxwidth: 500
:linewrap: false
...

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

 とり...

reSTによるドキュメント作成（記述）
 reST = reStructuredText
 http://sphinx-users.jp/doc10/rest.html
...

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

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

Demo
============
大見出し ...

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

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

応用例(2/2) blockdiag拡張の利用
 インストール (スタンドアロン版なら導入済み)
C:¥> easy_install sphinxcontrib-blockdiag
...

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

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

Sphinxドメイン
 ある言語を説明するマークアップとSphinx内のオブジェ
クトのリンク
 Python以外にも多くの言語に対応&独自に作成可能
(Erlang, Ruby, C++, JavaScript…)
 ドキュメ...

Sphinx一問一答

Sphinxのアイコン怖いよ？

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

ホルスの目は1/2から1/64の分数を表す楔形文字で構成
さ...

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
 イベント:
...

Share Slideshare

LinkedIn
Facebook
Twitter

Embed

Size (px)

Show related Slideshows at end

WordPress Shortcode

Link

Share
Email

ドキュメントを作りたくなってしまう魔法のツールSphinx by Takayuki Shimizukawa 92360 views
やりなおせる Git 入門 by Tomohiko Himura 86399 views
Sphinxで社内勉強会(Git)の 資料を作ってみた by Taku SHIMIZU 14077 views
Sphinx で手軽に作るドキュメント by Go Yamada 9614 views
ドキュメントシステムはこれを使え2015年版 by Keiichiro Shikano 41961 views
もしWordPressユーザーがGitを使ったら〜WordPress... by Takashi Uemura 198940 views

View on Slideshare

1 of 126 Ad

View on Slideshare

1 of 126 Ad