Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.

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

10,616 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!

×