Sphinx ではじめるドキュメント生活 2013 #sphinxconjp

9,066 views

Published on

Published in: Technology

Sphinx ではじめるドキュメント生活 2013 #sphinxconjp

  1. 1. Sphinx-users.jp 小宮健
  2. 2. お前だれよ Twitter: @tk0miya 仕事  (株)タイムインターメディア所属  テクニカルオフィサ(技術責任者)として活動 参加コミュニティ  Sphinx-users.jp  Python mini hack-a-thon Sphinx を中心にツールを開発  blockdiag シリーズ  Sphinx 拡張機能の開発  Googlechart やカレンダー機能 #bookathon 他読書会やってます
  3. 3. アンケート Sphinx 使っていますか? 1. 初めて聞いた 2. 名前は聞いたことはある 3. インストールはしてみた 4. もう使ってるよ
  4. 4. Sphinx-users.jp 小宮健
  5. 5. アジェンダ1. Sphinx について2. Sphinx の現在3. Sphinx の未来4. Sphinx コミュニティの紹介5. まとめ
  6. 6. Sphinx とは? Georg Brandl 謹製のドキュメントツール オープンソース (BSD ライセンス)
  7. 7. Sphinx の特徴 テキストから各種フォーマットへの変換  HTML, PDF など多くのフォーマットに対 応
  8. 8. Sphinx の特徴
  9. 9. Sphinx の特徴 シンプルなマークアップ  reST (reSTructured Text)  Wiki 記法みたいなもの ====== 見出し ====== * 箇条書き * 箇条書き 目次(toctree)ベースで文書構造を作る
  10. 10. Sphinx のよいところ ソースがテキスト形式  環境/エディタを選ばない  バージョン管理できる  ツールで自動生成しやすい  例) schema2rst (DB定義抽出) 機能を拡張することが出来る  Sphinx 拡張やテーマで表現力アップ 目次(toctree)ベースなので文章が書きやすい
  11. 11. Sphinx のいまいちなところ 変換する必要がある  reST を書いて make する、の繰り返し  ツールを使って自動化できるが… reST は文書レイアウトを表現できない  右寄せ、センタリング、二段組などの表現が ない  割り切りが必要 画像や図などは別途作る必要がある  Office スイートになれていると、ちょっと不 便 :-(
  12. 12. Sphinx の主な用途 開発ドキュメント  Python 等 OSS のドキュメント  設計書、マニュアルなど Web サイト  ブログ風、コーポレートサイト 出版  エキスパート Python プログラミング  Python プロフェッショナルプログラミング  その他多数
  13. 13. 他のツールとの比較 Word  ◯ 縦書き表記ができる  ◯ 日本語の文法チェック機能がある  ◯ 変更履歴の管理がしやすい  ◯ 画像や図の差し込みが簡単  ✕ 文書構成をいじるのが大変  ✕ 複数人で管理するのもやりづらい  ✕ Office スイートが必要
  14. 14. 他のツールとの比較 Excel  ◯ 誰でも使える。事実上の標準ツール  ◯ 方眼紙ライクな図、説明が書きやすい  ✕ 文章構成が存在しない  ✕ 編集、とくにセルの調整を始めると…  ✕ 印刷しづらいドキュメントができる  ✕ Office スイートが必要
  15. 15. 他のツールとの比較 Wiki  ◯ ブラウザだけで編集できる  ◯ 記法がわかりやすく書きやすい  ✕ 図や画像は別途作成する必要がある  ✕ 構成がネットワーク状で迷子になりやす い  ✕ 文書レイアウトは指定しづらい(できな い)
  16. 16. 他のツールとの比較 Sphinx-users.jp コンテンツの拡充 readthedocs の登場 日本語 PDF 環境の整備 Sphinx 拡張の増加 Sphinx テーマの増加 利用事例の増加
  17. 17. Sphinx-users.jp コンテンツの拡充 http://sphinx-users.jp/ 初心者向けコンテンツ Tips 集  PDF 出力やテーマ  各種拡張の紹介 逆引き辞典 イベント情報
  18. 18. readthedocs の登場 Sphinx ドキュメントのホスティングサー ビス ドキュメントをビルド、公開してくれる GitHub や BitBucket などにコミットする だけ 文章を書いて公開するのが簡単に
  19. 19. 日本語 PDF 環境の整備 日本語 PDF は環境設定が大変だった 打田さんの手によって環境が整ってきた 1. Sphinx にパッチを当てる 2. TeXLive (2011以降)を入れる 3. conf.py をいじる 4. make latexpdfja を実行する パッチは本家への取り込みを申請中 詳細な手順は sphinx-users.jp で!
  20. 20. Sphinx 拡張の増加 様々なメディアに対応する拡張  Youtube, Slideshare, Google Maps 図形を簡単に書くための拡張  blockdiag, seqdiag, plantuml reST を書きやすくする拡張  wikitable, japanesesupport その他  テーマ追加、装飾追加(取り消し線、赤字な ど)
  21. 21. Sphinx テーマの増加 theme.core 拡張によりテーマの追加が可能 に スライド系のテーマ  S6 (sphinxjp.themes.s6)  htmlslide (sphinxjp.themes.htmlslide)  impressjs (sphinxjp.themes.impressjs) 格好いいテーマ  bizstyle (sphinxjp.themes.bizstyle)  Solarized (sphinxjp.themes.solarized)
  22. 22. 利用事例の増加 OSS での利用は順調に増加  Python 本体、様々なライブラリ  Python 以外でも利用され始めている  Symphony2, CakePHP 伝聞では、業務での利用が増えている  社内では HTML で共有  PDF に変換して納品 コーポレートサイトに利用されている例も!
  23. 23. Sphinx の未来 日本語 PDF のパッチ取り込み  標準で PDF が生成できるように  次バージョン(1.2)でリリースされる 変換の自動化  Jenkins での変換/公開を簡単にしたい PDF テーマ  PDF 出力した時の見栄えを変更したい  TeX の知識がなくても変更できるように
  24. 24. Sphinx の未来 テーマや拡張をさらに増やす  まだ表現できないものも多い  画像など手間のかかるものもある  選択肢と自由度を上げていきたい Sphinx Web エディタ  ブラウザだけで文章を編集したい  より Wiki の手軽さに近づけていく 利用事例  仕事で使えると幸せになれるはず!
  25. 25. Sphinx の未来 Sphinx を使いはじめるための書籍を書きます テーマ (候補)  基本的な使い方  代表的な拡張の使い方  テーマの使い方、作り方  その他
  26. 26. Sphinx-users.jp Sphinx コミュニティの運営  メーリングリスト  Twitter (#sphinxjp) サイトの運営、マニュアルの翻訳 イベント開催  Sphinx+翻訳 Hack-a-thon (東京)  Sphinx 朝会 (大阪)  Sphinx ハンズオン  SphinxCon JP 2012
  27. 27. Sphinx で困ったら… Sphinx-users.jp に相談してください Twitter、ML、イベントなんでも構いませ ん  質問してみる  回答してみる  共有する
  28. 28. イベント開催予定 Sphinx+翻訳 Hack-a-thon  基本的に毎月開催  Connpass にて募集  Hack-a-thon スタイル、雑談の場
  29. 29. まとめ Sphinx について Sphinx の現在 Sphinx の未来 Sphinx コミュニティの紹介 Sphinx+翻訳 Hack-a-thon 10月もやるよ Enjoy Documentation!

×