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

8,039 views

Published on

Published in: Technology
0 Comments
14 Likes
Statistics
Notes
  • Be the first to comment

No Downloads
Views
Total views
8,039
On SlideShare
0
From Embeds
0
Number of Embeds
2,835
Actions
Shares
0
Downloads
18
Comments
0
Likes
14
Embeds 0
No embeds

No notes for slide

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!

×