1. 日本UNIXユーザ会 2011年6月勉強会
Sphinx-users.jp
小宮健、清水川貴之

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

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

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

6. システムは育つ
 システムは頻繁に形を変えていく
 機能、画面の追加
 システム増強
 ドキュメントはシステムの鏡
 システムの変更が反映されるべき
 だが、実際には反映されていないことが多い
 カラムが合わないテーブル定義
 足りない機能一覧
 削除されたページが載っている画面遷移図

7. もしドキュメントが無かったら…?
 ドキュメントが必要とされる場面
 新しいメンバーが参画するとき
 他のメンバーへの引き継ぎ時
 システムのトラブルが発生したとき
 もしこれらの場面でドキュメントが無かったら…?
 あとでドキュメントを作ると高いコストを支払うことになる
 いつでも手間をかけずに正確な情報へアクセスしたい

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

9.  内容が正確であること
 ドキュメントの内容が現在のシステムと一致している
 システムの変更内容が反映されている
 ドキュメントを読んでシステムを把握できる
 正確でないドキュメントは悪影響ばかり
 あなたは間違っているドキュメントを読みますか?

10.  簡単に書けること
 ドキュメントに集中できる環境
 ツールによるアシスト
 テンプレートによる構成の再利用
 体裁や形式ではなく、書くべき内容に注力できるように
 書きづらいドキュメントはメンテナンスされない
 ドキュメントを書くのがイヤだと感じたことはありませんか?

11.  誮もがいつでも参照・更新できること
 ドキュメントがメンバー全員に共有されている
 システムの知識を持った人が更新する
 新しい情報が分かったらなるべく早く更新する
 更新のタイミングを逃すとそのままになってしまう
 「あとで書こう」を忘れてしまったことはありませんか?
 「どこかにあったはず」と探し続けたことはありませんか?

12. 求められるドキュメントとは
 必要とされるドキュメントの三つの特徴
 内容が正確であること
 簡単に書けること
 誮もがいつでも参照・更新できること
 分厚いドキュメントの山では変化に対応できない
 必要なのはシンプルで変化に耐えうる軽量なドキュメント
 Lightweight Documentation
 ドキュメント作りを開発・運用サイクルに組み込む

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

14.  Lightweight Documentation を実現するツール
 各種 Wiki クローン
 Sphinx
 blockdiag シリーズ
 Javadoc
 これらのツールを組み合わせてサイクルを回す

15. まとめ
 ドキュメントは常に必要とされている
 システムの理解・把握や情報共有
 ドキュメント書いてますか?
 必要とされるドキュメント
 内容が正確であること
 簡単に書けること
 誮もがいつでも参照・更新できること
 Lightweight Documentation
 ツールを組み合わせて、変化に対応する

17. blockdiag シリーズ
 ドキュメントには図がつきもの
 システム構成図
 画面遷移図
 フローチャート
 UML 系の図 (クラス図、シーケンス図など)
 ネットワーク図
 図を作るのはとても手間がかかってしまうもの
 = Lightweight ではない！

18. blockdiag シリーズ
 テキストを図に変換するツール群
 blockdiag：ブロック図、画面遷移図、フローチャート
 seqdiag：シーケンス図
 actdiag：アクティビティ図
 nwdiag：ネットワーク図
 blockdiag は定義ファイル(テキスト)から画像を生成する
 レイアウトは自動的に行われる
 多くの図形作成ツール(GUI ベース)と異なる考え方

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

20.  blockdiag シリーズのキーワード
 メンテナンス性
 スピード感
 Enjoy
 Lightweight Documentation を支えるツールの一つ

21.  ドキュメンテーションツールとの連携
 Sphinx
 Redmine
 Trac
 moinmoin
 Mediawiki
 Web API
 既存のドキュメントに対して簡単に図を埋め込める

22. 他のツールとの比較
 ブロック図やシーケンス図を作るときに利用するツール
 Excel, Visio
 Cacoo
 astah*
 PlantUML
 多くのツールは要素を自分で並べていく必要がある
 意図したとおりに要素を並べることができる
 変更の際は並べ替え作業がメインになる

23. 追加/削除が大変
ここに 1 画面追加

24. 追加/削除が大変
１.スキマを作る

25. 追加/削除が大変
２.不要な矢印を消す

26. 追加/削除が大変
３.図形を配置する

27. 追加/削除が大変
４.矢印を調整

28. ずれる

29. ずれる

30. ずれる

31. ずれる

32. ずれる

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

34. blockdiag による図の生成
 図を生成する際は blockdiag コマンドを実行する
% blockdiag sample.diag # → sample.png

35. 定義ファイルの書き方 (blockdiag 編)
 blockdiag では「->」で要素を結びつけます
{
A -> B -> C;
}

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

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

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

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

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

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

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

43. 定義ファイルの書き方 (blockdiag 編)
 seqdiag では「->」「=>」で要素を結びつけます
{
// 呼び出し + 戻り方向のシーケンス
A => B;
// 一方向のシーケンス
A -> B;
}

44. 定義ファイルの書き方 (blockdiag 編)
 ブロックを使うとネストしたシーケンスを記述できる
{
A => B {
// B がアクティブな間のシーケンス
B => C;
}
}

45.  これらを組み合わせると複雑な図を書くことができます。
 認証システムのシーケンス図： http://bit.ly/lwvEox

46.  actdiag と nwdiag もシンプルな書式で図を作成できる
 actdiag: http://bit.ly/kkcgIg
 nwdiag: http://bit.ly/kR5tYF
 詳細は blockdiag.com のマニュアルを参照して下さい

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

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

49. まとめ
 blockdiag シリーズを使って図を楽に書こう
 並び替えや位置調整に手間をかけない
 図を作るのにスピードを与える
 Sphinx や Trac, Wiki と組み合わせると便利
 楽するためにはもっと知恵と経験が必要
 意見やアイディアを集めてもっと楽したい
 URL: http://blockdiag.com/
 Twitter: #blockdiag
 Google グループ: blockdiag-discuss

51. 自己紹介： 清水川 貴之
http://清水川.jp/ @shimizukawa
 仕事
 株式会社BeProud
 Djangoを使い始めました
 オープンソースコミュニティー活動:
 Sphinx-users.jp 副会長
 Zope/Plone 運営
 その他, pyspa系, XP系
 言語:
 C++/C/8086 -> Python/Rails
 書籍
 エキスパートPythonプログラミング(翻訳)
 アスキー・メディアワークス

52. イベントの紹介
 エキスパートPythonプログラミング読書会
 6/19(日) 明日です！
 場所: 大阪
 参加方法: ATND http://atnd.org/events/16731
 PyCon JP 2011
 8/27(土)
 場所: 東京
 参加方法: 7月に募集開始予定
 URL: http://2011.pycon.jp/

54. Sphinxとは何か
ドキュメントを作りたくなってしまう
魔法のツール

55. Sphinxとは何か
テキストエディタが
あれば編集可能

56. Sphinxとは何か
様々な出力
形式に対応

57. Sphinxとは何か
マニュアル作成から
サイト構築まで
応用しやすい

59. 最近Sphinx利用者が増えています
JUS勉強会(2010/12/3)

60. 最近Sphinx利用者が増えています
Sphinx+翻訳Hack-a-thon(2011/2/12)

61. 最近Sphinx利用者が増えています
JUS勉強会(2011/6/18)

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

63. こんなところで使われています
多くのドキュメントでの
利用実績多数！
 国内： http://sphinx-users.jp/example.html
 国外： http://sphinx.pocoo.org/examples.html

65. Sphinxの特徴
プレーンテキストなソースコード

66. Sphinxの特徴
プレーンテキストなソースコード
メモ帳でも
編集可能

67. Sphinxの特徴
ページ間の相互リンク

68. Sphinxの特徴
ページ間の相互リンク
ファイルリンク
用語リンク

69. Sphinxの特徴
強力なコードハイライト
実装言語とテンプレートとで200
前後の言語書式に対応
http://pygments.org/docs/lexers/

70. Sphinxの特徴
拡張機能で
さまざまなことができる

71. Sphinxの特徴
拡張機能で
さまざまなことができる
blockdiag拡張 UML描画
docx出力
HTML
テンプレート変更
Pythonコードから
数式描画
ドキュメント生成 楽譜描画

72. Sphinxの特徴
ドキュメントは
100%日本語化されている

73. Sphinxの特徴
ドキュメントは
100%日本語化されている
リファレンスマニュアル以外にも
チュートリアルなどドキュメント多数！

75. ドキュメントを書くのに、何を使用しています
か？
 ワープロソフト
 Word
 一太郎
 OpenOffice Writer
MicrosoftのOfficeの
テンプレートのサイトより転載

76. ドキュメントを書くのに、何を使用しています
か？
 表計算
 Excel
 Calc
MicrosoftのOfficeの
テンプレートのサイトより転載

77. ドキュメントを書くのに、何を使用しています
か？
 プレゼンテーション
 PowerPoint
 KeyNote
 OpenOffice Impress

78. ドキュメントを書くのに、何を使用しています
か？
 それ以外
 Wiki
 HTML手書き
 TeX

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

80. Word - pros
http://www.flickr.com/photos/jetalone/861945664/
CC BY by jetalone

81. Word - pros
 縦書きで編集できる
 文法チェックしてくれる
 差分比較機能がある
 参考文献、索引、
差し込み印刷etc…
http://www.flickr.com/photos/jetalone/861945664/
CC BY by jetalone

82. Word - cons
http://www.flickr.com/photos/jetalone/861945664/
CC BY by jetalone

83. Word - cons
 巨大な1ファイルになる
 探すのが大変
 複数人で編集が大変
 章の入れ替えとか厳しい
http://www.flickr.com/photos/jetalone/861945664/
CC BY by jetalone

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

85. Excel - pros
 Excel扱える人は多い
 ぱっと作るのは早くできる
 ロジカルシンキング的に苦心しなくても、罫線で武装する
と、見た目が立派に見える
http://www.flickr.com/photos/21183810@N00/43665
18191/ CC BY-NC-SA by Jerome Rothermund

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

87. Excel - cons
 ワークシートで分断され、閲覧性が悪い
 内容の追加でレイアウトの修正が必要になると、修正に
膨大な時間がかかる
http://www.flickr.com/photos/21183810@N00/43665
18191/ CC BY-NC-SA by Jerome Rothermund

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

89. Wiki - pros
 圧倒的に柔軟
 構造化されていなくても、とりあえず入れておける
 複数人での編集・閲覧ができる
http://www.flickr.com/photos/7506006@N07/1197395511
/ CC BY-NC-ND by milky.way

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

91. Wiki - cons
 文章の構成、質の維持に目を光らせる必要がある
 あるいは、Wikipediaのように構成を決めておく
 全体の構成を修正するのに手間がかかる
 トップダウン型ではないので、まとめて印刷や他形式に変
換がやりにくい
http://www.flickr.com/photos/7506006@N07/1197395511
/ CC BY-NC-ND by milky.way

92. Sphinx - pros
http://www.flickr.com/photos/18261299@N00/44724083
86/ CC BY-SA by sweet_redbird

93. Sphinx - pros
 ドキュメントの背骨がしっかりさせる
 有機的に文章を繋げる仕組みを持っている
 説明ユニット
 プレーンテキスト。バージョンコントロールOK！
http://www.flickr.com/photos/18261299@N00/44724083
86/ CC BY-SA by sweet_redbird

94. Sphinx - cons
http://www.flickr.com/photos/18261299@N00/44724083
86/ CC BY-SA by sweet_redbird

95. Sphinx - cons
 背骨を気にして、コンテンツを追加する必要
 マークアップを覚える
 WYSIWIGではない
http://www.flickr.com/photos/18261299@N00/44724083
86/ CC BY-SA by sweet_redbird

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

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

99. Sphinxのインストール(Windows)
 必要なもの
 Sphinxスタンドアロンインストーラのみ
 Sphinx-1.0.7.20110618-py2.7-win32.exe
これ一つでblockdiagシリーズも導入完了！
Demo
ただし、まだ実地検証が足りないため、みなさんのレポート
お待ちしております！

101. Sphinx拡張
 拡張をすることで様々な要求に対応できる
 新たな出力形式に対応したい
例: docx形式で出力したい
 マークアップを拡張したい
例: blockdiagを埋め込みたい
 HTMLテンプレートを追加したい
例: 業務向きなシンプルなのが欲しい
 デフォルトで組み込まれている拡張が多数！

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

103. サードパーティのSphinx拡張
 その他特筆すべき拡張
 blockdiagシリーズ
 ブロック遷移図を簡単な記述で作成！
 sdedit
 UMLでシーケンス図を描けます！
 sphinxjp.themes
 HTMLテーマをいくつか追加
 docxbuilder（開発中）
 SphinxでWordファイルを作成

104. blockdiag by @tk0miya
 ブロック遷移図を文字のみで書けます
 sphinxcontrib-blockdiag でSphinxでブロック遷移図を
書くことが可能
.. blockdiag::
diagram webapp {
login -> something -> logout -> login
}

105. 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のインストールが必要

106. sphinxjp.themes by @shimizukawa他
sphinx-users.jpスタイル
プレゼン表示(s6)

107. docxbuilder by @shimizukawa
 SphinxからWord形式で出力する拡張
現在開発中
です

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

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

111. Sphinxによるドキュメントの生成（ビルド）
 自動作成されたMakefileをそのまま利用するだけ
$ make html
Demo
============
大見出し 大見出し
============
中見出し
見出し
========= ・リストアイテム1
・リストアイテム2
-リストアイテム1 1. 自動採番アイテム1
-リストアイテム2 2. 自動採番アイテム2
#. 自動採番アイテム1
#. 自動採番アイテム2

112. 応用例(1/2) 出力形式の変更
 HTML以外にもデフォルトでLaTeX、PDF 、ePubに
$ make latex
$ make latexpdf
$ make epub
 HTMLもデフォルトで複数のテーマを使用可
Demo

113. 応用例(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; }

114. テンプレートの作成
 テンプレートエンジン “Jinja2”を利用している
自分でテンプレートを作成することも可能
 大まかに分けて2つのhtmlを作成する
 ドキュメント全体の基礎 : layout.html
 各ページ : page.html
 デフォルトテーマ basic のテンプレート継承により時間が
削減

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

117. Sphinx一問一答
Sphinxのアイコン怖いよ？

118. ホルスの目
このアイコンはSphinxの本家サイトで使用されているアイコ
ンで、「ホルスの目」と言います。エジプトではスフィンクスは
太陽の神ホルスの一面であると考えられています。
ホルスの目は1/2から1/64の分数を表す楔形文字で構成
されており、これを全部足すと63/64という1の近似に。
これが「ホルスの目分数」で、トト神が魔法で補って1になる
らしい。
「魔法のツールSphinx」
にふさわしいですね。

119. Sphinx一問一答
Wordのようなエディタは
ありますか？

120. Sphinx一問一答
Wordのドキュメントが
たくさんあるんですが、
Sphinxに変換する拡張は
ありますか？

121. Sphinx一問一答
PowerPointに
出力出来ますか？

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

123. 逆引き辞典
逆引き辞典、
出来ました (@r_rudi)
http://sphinx-users.jp/

124. Sphinx一問一答
皆さんの疑問・質問・要望を
教えてください！

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