1. Sphinx-users.jp
小宮健

2. お前だれよ
 仕事
 (株)タイムインターメディア所属
 テクニカルオフィサ(技術責任者)として活動
 参加コミュニティ
 Sphinx-users.jp
 Python mini hack-a-thon
 Sphinx を中心にツールを開発
 blockdiag シリーズ
 Sphinx 拡張機能の開発
 Googlechart やカレンダー機能
 #bookathon 他読書会やってます
Twitter: @tk0miya

4. Excel 方眼紙撲滅委員会とは
 Excel 方眼紙を撲滅するための秘密結社
 表計算はいいと思います
 ツールを作って/使って楽したい
 要は『適材適所』しようということ
 ひとり委員会です。

5. 前回までのあらすじ
 Excel方眼紙を廃止するためにツールを
作った
 blockdiag シリーズ
 テキストから画像を生成するツール群
 ブロック図、シーケンス図、ネットワーク
図など

6. blockdiag の例
 このテキストが…
{
トップページ -> ログイン -> マイペー
ジ;
トップページ -> 商品一覧 -> 商品詳細;
}

7. seqdiag の例
 このテキストが…
{
A => B => C;
}

8. nwdiag の例
 このテキストが…
{
network { web01; web02; }
network { web01; web02; db01; }
}

10. 今回のターゲットはドキュメント
 ドキュメントとしても Excel は使われてる
 バージョン管理が難しい
 基本設計書_20130901.xlsx
 基本設計書_20130901_2.xlsx
 基本設計書_20130901最新.xlsx
 もちろんマージできない
 差分管理が難しい
 やはり Excel は撲滅されるべきである！
 そうだ、Sphinx を使おう

11. Sphinx とは
 テキスト(reST)から各種フォーマットへ変
換
 HTML, PDF など多くのフォーマットに対
応

12. Sphinx とは

13. Sphinx の特徴
 シンプルなマークアップ
 reST (reSTructured Text)
 テキストのままでも見やすい
======
見出し
======
* 箇条書き
* 箇条書き

14. Sphinx のよいところ
 ソースがテキスト形式
 環境/エディタを選ばない
 バージョン管理できる
 ツールで自動生成しやすい
 例) schema2rst (DB定義抽出)
 機能を拡張することが出来る
 Sphinx 拡張やテーマで表現力アップ
 目次(toctree)ベースなので文章が書きやすい

15. Sphinx のいまいちなところ
 変換する必要がある
 reST を書いて make する、の繰り返し
 ツールを使って自動化できるが…
 reST は文書レイアウトを表現できない
 右寄せ、センタリング、二段組などの表現が
ない
 割り切りが必要
 画像や図などは別途作る必要がある
 Office スイートになれていると、ちょっと不
便 :-(

16. Sphinx の主な用途
 開発ドキュメント
 Python 等 OSS のドキュメント
 設計書、マニュアルなど
 Web サイト
 ブログ風、コーポレートサイト
 出版
 エキスパート Python プログラミング
 Python プロフェッショナルプログラミング
 その他多数

17. 他のツールとの比較
 Excel
 ◯ 誰でも使える。事実上の標準ツール
 ◯ 方眼紙ライクな図、説明が書きやすい
 ✕ 文章構成が存在しない
 ✕ 編集、とくにセルの調整を始めると…
 ✕ 印刷しづらいドキュメントができる
 ✕ Office スイートが必要

18. 他のツールとの比較
 Wiki
 ◯ ブラウザだけで編集できる
 ◯ 記法がわかりやすく書きやすい
 ✕ 図や画像は別途作成する必要がある
 ✕ 構成がネットワーク状で迷子になりやす
い
 ✕ 文書レイアウトは指定しづらい(できな
い)

19. 他のツールとの比較
 POD
 ◯ エディタだけで編集できる
 ◯ 書き慣れている
 ✕ 図や画像は別途作成する必要がある
 ✕ 文書レイアウトは指定しづらい(できな
い)
 ✕ Perl モジュール以外のことは書きづらい

20. 『Sphinx をはじめよう』
 世界初のSphinx本
 電子書籍
 100ページ弱相当
 オライリー・ジャパン
 1,680円
 2013/9/13 発売
 ターゲット
 初めて使う人
 周囲への布教用

21. 今回のターゲットはドキュメント
 デモ
 時間があれば…

22. まとめ
 Sphinx 本書きました
 けっこう Sphinx 便利だと思います
 10月に Hackathon/ハンズオンやります
 イベントサイト connpass で募集中
 blockdiag もよろしく 

23. おまけ
 Pandoc を使って markdown を使うプラグイン書
きました
 Sphinx 文書に markdown フォーマットを利用す
る
 http://tk0miya.hatenablog.com/entry/2012/12/19/233642