Successfully reported this slideshow.
Your SlideShare is downloading. ×

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

Ad
Ad
Ad
Ad
Ad
Ad
Ad
Ad
Ad
Ad

Check these out next

1 of 35 Ad
Advertisement

More Related Content

Slideshows for you (20)

Similar to Sphinx ではじめるドキュメント生活 2012 #pyconjp #sphinxconjp (19)

Advertisement

More from Takeshi Komiya (20)

Recently uploaded (20)

Advertisement

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

×