1. Sphinx-­‐users.jp
渋川よしき、山口能迪、清水川貴之
日本UNIXユーザ会
2010年12月勉強会

2. 自己紹介
 山口能迪（やまぐちよしふみ）

id
:
ymotongpoo
 「とんぷー」と呼んでください
 OSSのドキュメント翻訳をしています
 Tornado
（軽量Webフレームワーク）
 Redis
（高機能KVS）
 Jinja2
（テンプレートエンジン）
など

3. 自己紹介：渋川よしき
 仕事
 大手製造業の社内SE
 社外で技術習得して社内で楽をする
 参加コミュニティ
 SphinxUsers.jp会長
 翻訳ハッカソンとかを継続開催予定
 日本XPユーザグループ代表
 とちぎRuby
 Python温泉(系)
 11/14にPython
Hack-­‐a-­‐thon
 今年出した本
 IT業界を楽しく生き抜くための
つまみぐい勉強法(技術評論社)
 エキスパートPythonプログラミング
(アスキーメディアワークス
 電子出版文書フォーマット技術動向調
査(インプレスR&D)
Twitter:
@shibukawa
写真:
清水川webより転載

4. 自己紹介： 清水川 貴之
http://清水川.jp/
@shimizukawa
 オープンソースコミュニティー活動:
 Sphinx-­‐users.jp
副会長
 Zope/Plone
運営
 その他,
pyspa系,
XP系
 言語:
 Python,
Rails,
昔はC++/C/8086
 仕事:
 フリーでPython/Railsやってます
 翻訳本
 エキスパートPythonプログラミング
 アスキー・メディアワークス
 B5変
416ページ

6. 3分説明
 プレーンテキストのファイルから、各種形式のファ
イルをエクスポートするプログラム

7.  拡張機能で、機能を追加していくことができる
 ドキュメントは100%日本語化されている
 sphinx-­‐user.jp
 強力なコードハイライト
 利用実績多数！
 国内：
http://sphinx-­‐users.jp/example.html
 国外：
http://sphinx.pocoo.org/examples.html

9. お品書き
 デモ
1. Sphinxのインストール
2. Sphinxプロジェクトの作成
3. reSTによるドキュメント作成
4. Sphinxによるドキュメントのビルド
 応用例（ビルド、テンプレート）
 サイト
 拡張について

10. 1/4
Sphinxのインストール
 2分で始めましょう！
 必要なもの
 Python,
easy_install,
Sphinxの3点セット
 パッケージ管理ツールを使えば一瞬
 Ubuntu
 Mac
OS
X
 準備完了です
$
sudo
apt-­‐get
install
python-­‐sphinx
$
sudo
port
install
python-­‐sphinx

11. 2/4
Sphinxプロジェクトの作成
 “sphinx-­‐quickstart”を使います
 とりあえずはEnterを連打！
 conf.pyとディレクトリが作成
 この3つだけは回答する
 プロジェクト名
 バージョン番号
 著者名
$
mkdir
Unix-­‐How-­‐to
$
cd
Unix-­‐How-­‐to
$
sphinx-­‐quickstart
Demo
.
├──
Makefile
├──
_build
├──
_static
├──
_templates
├──
conf.py
├──
index.rst
└──
make.bat

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

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

14. 応用例
1/2
 HTML以外にもデフォルトでLaTeX、PDF
、ePubに
 HTMLもデフォルトで複数のテーマを使用可
$
make
latex
$
make
latexpdf
$
make
epub
Demo

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

16. Sphinx実用例
 多くのOSSドキュメントやサイトで採用実績あり
 Python
2.6.2ドキュメント
 OpenPNE
Web
API仕様書
 groongaドキュメント…他多数
 テンプレート機能を用いてサイトを構成

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

18. Sphinx拡張
 拡張をすることで様々な要求に対応できる
 新たな出力形式に対応したい
 マークアップを拡張したい
 Sphinx拡張とは言うものの
デフォルトで組み込まれている拡張が多数！

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

20. サードパーティのSphinx拡張
 その他特筆すべき拡張
 sdedit
 UMLを描けます！
 blockdiag
 ブロック遷移図を簡単な記述だけで作成
 docx
 SphinxでWordファイルを作成

21. 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()

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

23. docx
 SphinxからWord形式で出力する拡張
 現在誠意開発中
by
清水川さん

24. まとめ
 Sphinxは
 インストールが簡単
 設定も簡単
 書くのも簡単
 ビルドも簡単
 カスタマイズも簡単
 拡張もできる
 サイトも作れる
という素晴らしいドキュメントツールだった！

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

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

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

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

30. Word
Excel
Sphinx
Wiki
http://www.flickr.com/photos/boothy/26461481/
CC
BY-­‐NC
by
Dr
Snafu
http://www.flickr.com/photos/omeyamapyonta/
3052096093/
CC
BY-­‐SA
by
PYONKO
http://www.flickr.com/photos/johncarleton/2367673332/
CC
BY-­‐NC-­‐SA
by
John
Carleton
http://www.flickr.com/photos/stompy/11300916/
CC
BY-­‐
NC
by
Abizern

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

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

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

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

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

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

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

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

40. 成長のポイント
 背骨
 toctree！toctree！toctree！
 神経のネットワーク
 セマンティックスを定義していく

41. 背骨の肝：セクションタイトル
 ドキュメントを構成する重要な要素
 #,
*,
=,
-­‐,
^,
~,
“などの記号で下だけ、上下を囲う
 自分なりのルールを決めておくと良い
 単体のソース内の登場順でH1,
H2,
H3..が決まる
 文字長よりも短いと警告が出ます
========
はじめに
========
想定読者
========
新人社会人
----------
はじめに
想定読者
新人社会人

42. 背骨の肝：親子関係の定義
 Sphinxの一番重要な部分
 toctreeディレクティブを使って定義する
 拡張子なしのファイル名を列挙する
 目次がその場で作られる
..
toctree::
:maxdepth:
2
preface
overview/index
defensive/index

はじめに

本書の考えるゴール

本書を作るにあたって

本書で説明していくこと

つまみぐい勉強法

勉強はつまみぐいから

大切なことは、継続

自分に合うものを選ぼう

終着点は自分で決めよう

43. 背骨の肝：親子関係の定義
 セクションタイトルを子供の文書から引っ張ってき
て目次を作る
 toctree自体は1文書に何個も書ける
 toctree表示位置に、子供の文書のセクション構造が
挿入される
toctreeができたら、Sphinx黒帯！

44. どこからどう書いていく？

45. 神経ネットワーク
 巨大なドキュメントをどう作る？

46. 神経ネットワーク
 巨大なソフトウェアをどう作る？
• モジュール化
• 単独のプログラム+シェル(UNIX的アプローチ)
• 公開インタフェースによるアクセス(粗結合)
• メタプログラミング

48. セマンティック
 定義(説明ユニット)とそこへのリンク
 ソースコードの構成要素の説明とリンク
..
module::
berrymq
..
function::
talk(識別子)
メッセージを送ります
クライアントとコネクションを張っ
たら
:func:`talk`
が使えるように
なります
berrymq.talk(識別子)!
メッセージを送ります"
クライアントとコネクションを張っ
たら
talk()
が使えるようになり
ます
ディレクティブ
ロール
..
_名前:
:ref:`名前`
..
function::
名前
:func:`名前`
..
method::
名前
:meth:`名前`
ディレクティブ
ロール
..
module::
名前
:mod:`名前`
..
class::
名前
:class:`名前`
..
attr::
名前
:attr:`名前`

49. ドキュメントのモチベーションを上げ
 いろんなやる気のスイッチを活用
 全体像を見て、足りない項目を補完
 とにかく、細かい部分から徹底的に丁寧に
 索引を見て、索引を充実させる
 読む人ごとの入り口を作ってみる
 いろんなフォーマットで出力してみる

50. 対象
• ソフトウェア開発プロジェクト
• 規模：１名∼１０名前後

51. ドキュメント、書いてますか？
ソフトウェア開発プロジェクト
規模：１名∼１０名前後

52. ドキュメントを書いている割合
40%くらい
は書いて
る？
60%
書いていない

53. ドキュメントが書けない開発現場
なぜドキュメントを書けないの？
 どこに書いて良いか分からない
 何を書いて良いか分からない
 どう書いて良いか分からない
 どんなツールを使えばいいか分からない
 どこに置けばいいか分からない
 どうせドキュメントなんて誰も見ない
 ドキュメントはあとで書けばいい
 ドキュメントを書く時間がない
 めんどくさい
 楽しくない

54. ω･`)
・・・

55. 意味あるドキュメントを書いている割合
？

56. 問題と対策
ドキュメント作成をさぼってしま
う原因
原因を取り除いてしまおう
 どういう構成で書いたら良いか
分からない
 自分は文章を書くのが苦手だ
 誰も見ない文章は書きたくない
 開発終了に向かうにつれて時間
がなくなる
 プロジェクト開始時に構成
を整備しておく
 書き方の指針を決めておく
 能動的にドキュメントを書
くよう動機づける
 先にドキュメントを書くよ
うにする
簡単！
面倒..

57. ゴール
1. ドキュメントを簡単に書けるようにする
2. みんなが能動的にドキュメントを書くよう
に
動機付ける
3. 開発物の品質向上へフィードバックする
4. 今回の成果から構成のスケルトンを作成し
再利用する

58. ドキュメントを簡単に書けるようにする
簡単に書ける、って何だろう？

59. ドキュメンテーションの速度アップ
始めのハードルを下げて
スピーディーに書けるようにしよ
う

60. 書き方のルールを決めておく
「技術文書を書くための7つのルール」を押さえてお
こう！
1. ２つのステップで書く
2. 読者のターゲットを明確にする
3. シンプルなスタイルを使用する
4. 情報のスコープを絞る
5. 実在するようなコードのサンプルを使用する
6. なるべく少なく、かつ十分なドキュメント
7. テンプレートの使用
「エキスパートPythonプログラミング」 10章
（アスキーメディアワークス刊）より抜粋
10章: プロジェクトのドキュメント作成 （無料公開中）

61. 読者ターゲット別に大きく分ける
誰が読むべきものかを意識して構成を作る。
例えば以下のように構成。
マネージャ向け
設計者向け
開発者向け
運用者向け
APPENDIX

62. ドキュメントを書くための手間を減らす
 開始時に分かっている共有情報を
予め書いておく
 数ステップでドキュメントを書く環境を
整えられるようにする
 共有や閲覧の仕組みを自動化して
開発プロセスに組み込む

63. デモ
もし今日の発表者3名がJUS商事
の『サービス基盤構築』を開発
したら

64. Step1
Sphinxの初期ドキュメントから始める
C:>
sphinx-­‐quickstart

65. Step2
ドキュメントの最初のアウトプットを作成
 読者のターゲット別に章節の構成をおおまかに用意

66. Step3
既に分かっている情報を追加
 マネージャー、設計者、開発者それぞれに必要とな
る、
プロジェクト特有の情報を記載

67. Step4
段階的にドキュメントに記載
プロジェクトの進捗と共に
成長するドキュメント

68. 必要な文章を必要な時に書くようにする
いつドキュメントを更新する？
いつで
も！

69. ドキュメント駆動開発
まず目的を書こう

70. デモ
Pythonのドキュメント駆動開発

71. 能動的にドキュメントを書く動機付け
品質へのフィードバック

72. 繋がりを加速する
自動化のすゝめ

73. ドキュメント作成を開発サイクルに組み込む
継続的インテグレー
ション
課題管理
環境構築
リポジトリ
自動テスト
環境構築
自動テスト
本番環境
環境構築
ドキュメン
ト
生成
ドキュメント
生成
実装
ドキュメンテーション
XP祭り2010 資料より抜粋
Pythonで アジャイル開発サイクル 2010ver.
http://清水川.jp/docs/xpfest2010/

74. 全てを一体に
全体が繋がる楽しさ！

75. 次の開発のために
ドキュメントポートフォリオへ
の昇華
「エキスパートPythonプログラミング」 10章
（アスキーメディアワークス刊）より抜粋
10章: プロジェクトのドキュメント作成 （無料公開中）

76. まとめ
1. ドキュメントを簡単に書けるようにする
 ７つのルールと構成のテンプレート化
2. みんなが能動的にドキュメントを書くように動機
付ける
 ドキュメント作成と開発を一体化する
3. 開発物の品質向上へフィードバックする
 ドキュメント駆動開発＆フィードバックの形成
4. 今回の成果から構成のスケルトンを作成し再利用
 ドキュメントポートフォリオの構築

77. (´･ω･`)ノ
以上
業務での利用事例でした

78. 仕事でどうやって使ってる？
どうやって職場に広めよう？
コミュニティでの取り組など
質疑応答