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.

SIerでもSphinxを使いたい!総括

11,992 views

Published on

2014/10/26 SphinxConJP 2014発表用資料です。

Published in: Technology
  • Be the first to comment

SIerでもSphinxを使いたい!総括

  1. 1. SIerでもSphinxを使いた い! 総括 2014/10/26 SphinxCon JP 2014 @kk_Ataka
  2. 2. 自己紹介 4 Twitter: @kk_Ataka 4 GitHub: gosyujin 4 普段いるところ 4 Kawasaki.rb 4 Jekyllrb-ja(主催) 4 Python力 4 文法もまだあやしい
  3. 3. 発表の趣旨 4 SIerでもSphinxを使いたいので職場で奮闘してみた備忘録 4 利用事例 4 拡張の紹介 4 Kawasaki.rbというイベントで話した内容の総集編 4 できたこと、できなかったこと含めて駆け足で共有します 4 主観が多め
  4. 4. 今日話さないこと 4 Sphinxとはなんぞや 4 reST記法とはなんぞや 4 Sphinxのインストール方法とか使い方とか
  5. 5. アジェンダ 1. 競合ツールとの比較 2. 導入のためのあれこれ、または導入後の課題 3. 実際に導入してみた感想
  6. 6. 競合ツールとの比較
  7. 7. 競合ツールとの比較! 4 導入するためには上の人を説得するための政治が必要… 4 競合ツールと比較してよさ気と思ったことを伝えていく 1. Office(Word, Excel) 2. Wiki, Markdown 3. Sphinx 4 好きな言葉「適材適所」
  8. 8. 比較1 Office
  9. 9. Office 長所 4 SI界のスタンダード 4 WYSIWYGな操作 4 きめ細かいデザインが可能 4 図やフローの挿入が容易 4 誰のPCにも入っていて、誰でも使える
  10. 10. !?
  11. 11. Office 短所 4 あらゆるものがOfficeで作成され、至る所にちらかる 4 日付バージョン管理…(主観) 4 恐怖の「 議事録_20140505_2(最新)(xx修正).xls 」 4 検索性が非常に悪い 4 違うシートとか、吹出しとか 非表示とか…探せない…
  12. 12. Office 短所 4 diffが取るのがメンドくさい 4 取れないとは言ってない、最近は取れるっぽい 4 ミリ単位のレイアウト修正を強いられる 4 リストとかすぐ壊れる 4 内容を集中して書かせて! 4 (職人芸が発揮されるほど)重い
  13. 13. 番外 Officeのいいところ…カット!
  14. 14. Officeのいいところ 4 Officeでしかできないことも、ある 4 過去資料でいいところあげてます! 4 ようは適材適所でよろしくお願いします
  15. 15. 比較2 Wiki, Markdown と Sphinx
  16. 16. Wiki, Markdown と Sphinx の長所 Officeで短所として挙げた問題は解消できている!…と思う
  17. 17. Wiki, Markdown と Sphinx の長所 > あらゆるものがOfficeで作成され、至る所にちらかる 問題 4 プレーンテキストで作成される 4 Officeよりは探しやすいんじゃないかと思うのだが… 4 ブラウザ、エディタの検索とか、Wiki内検索とか
  18. 18. Wiki, Markdown と Sphinx の長所 > diffが取るのがメンドくさい 問題 4 Markdownはプレーンテキストなので簡単 4 バージョン管理もしやすい 4 Wikiもだいたい差分表示機能あり 4 diff取りやすい
  19. 19. Wiki, Markdown と Sphinx の長所 > ミリ単位のレイアウト修正 問題 4 出力先(html+css、pdfなど)である程度統一できる
  20. 20. Wiki, Markdown と Sphinx の短所 Officeでは特に意識していなかったことを考慮する必要あり
  21. 21. Wiki, Markdown と Sphinx の短所 4 記法を覚える必要がある 4 未経験者にちょい敷居が高い… 4 「特定部分のみ」のレイアウト修正 4 cssなどに独自の処理を入れなければならない 4 図やフローの挿入はタグで挿入 4 直感的にいじれない(現物をD&D…)
  22. 22. Wiki, Markdown の短所 4 検索性はあまりよくない 4 しっかり作れば… 4 それでもOffice + 共有サーバコンボよりは… 4 重い 4 体感としては Office > Wiki, Markdown > Sphinx 4 サーバ性能とか同時アクセス数によるけど
  23. 23. Sphinx だけの長所 4 体系的なドキュメントの骨組みを簡単に整えられる 強力な 機能がある 4 この辺をサクッとよろしくやってくれているのが doctree...である気がする(まだ未調査) 4 Wikiとかでこれを整備するのはちょっとしんどい
  24. 24. Sphinx だけの長所 4 検索性はよいと思う 4 体系的にまとまるため 4 軽い 4 Outputが静的ファイル 4 htmlをWebサーバに置けば静的ファイルを取ってくるの と変わらない
  25. 25. ここまでのまとめ 4 慣れ親しんだOfficeから脱却したい、管理しやすい形式で ドキュメント作成に挑戦してみよう 4 ならば Wiki, Markdown か Sphinx だ! 4 TipsとかならWiki, Markdownでもいいけど、ドキュメン トなのである程度体系的に管理したい 4 体系的に管理するのが得意な Sphinx だ! 結論: 一回Sphinxチャレンジしてみましょう!
  26. 26. 導入のためのあれこれ、 または導入後の課題
  27. 27. 導入するための壁 1. 対プロジェクトメンバー(PM)に対して(布教) 2. 対顧客に対して(納品)
  28. 28. 壁1. 対PM
  29. 29. 対PM 登場人物 4 自分 4 Sphinxを導入したい人、基本的になんでもやる 4 メンバー 4 導入したSphinxを使ってほしい人
  30. 30. 対PM 「自分」の仕事 4 今回はreSTで進めることの明確な宣言とサポート 4 一番大事 4 これができないと負の成果物が生成される…
  31. 31. 対PM 「自分」の仕事 4 メンバーが「rstファイルを開いてドキュメント作成」に注 力できる環境を作る 1. sphinx-quickstartで下準備 2. ドキュメント自体のアウトライン作成 3. doctreeの作成 などなど
  32. 32. 対PM 「自分」の仕事 4 ビルド環境、デプロイ環境などもお膳立て 4 ビルドはJenkinsなどで拾う 4 デプロイはApacheにhtmlファイル配備とか(お手軽)
  33. 33. 対PM 「メンバー」の仕事 4 reST記法を覚えてもらう 4 Markdown -> reST -> Outputという裏技もある (Pandoc経由) 4 バージョン管理ツールとかの話は…割愛
  34. 34. 対PM 課題 4 ローカルPCでのプレビュー 4 メンバーのPCにSphinxを入れてもらうのは厳しい… 4 そうすると、確認できるのがサーバにプッシュした時の みになってしまう 4 ローカルで簡単にreSTプレビューできないだろうか… 4 GitHubとか使えばある程度できるんだけど
  35. 35. 対PM 課題 4 プロジェクト(会社)の風土にあわせたカスタマイズが必要 かも 4 こういうレイアウトがいい 4 こういうヘッダフッタがほしい 4 こういう改訂履歴ページがほしい
  36. 36. 対PM 課題 4 今回は「変更履歴」出力プラグイン作ってみた 4 sphinxcontrib-releasenotesプラグイン 4 .. releasenotes:: ディレクティブを追加したところにGit のコミットログと差分を貼り付け 4 Git使えない人用
  37. 37. 壁2. 対顧客
  38. 38. 対顧客 登場人物 4 プロジェクト 4 Sphinxでドキュメント納品する側 4 顧客 (社内の人 or 社外の人) 4 ドキュメントを納品される側 4 歴史的経緯からOfficeで納品される事が多い 4 例外はJavadocとか?
  39. 39. 対顧客 「プロジェクト」側の仕事 4 Sphinxで作成するドキュメントに関して「今回はOfficeじ ゃない形式で設計書とか書きますよ」の合意を得とく
  40. 40. 対顧客 「顧客」側の仕事 4 特になし?心構えくらい?
  41. 41. 対顧客 課題 4 納品形式 最重要(次ページ参照) 4 納品後 「誰が」 保守するのか 4 顧客が巻取ってしまう場合、どう保守すればよいのか 4 要解決事項、誰かどうやってるか教えてください… 4 これが解決できないと、Sphinxは納品対象外ドキュ メントにしか適用できない…
  42. 42. 実際に導入してみた感想
  43. 43. 環境 4 3ヶ月位のほぼ1人プロジェクトで「社内資料」をSphinx! 4 社内資料なので、納品関係の課題はスルー 4 環境揃えたい放題 4 Git + Sphinx + Jenkins etc 4 途中で1人サポートに入ってもらった
  44. 44. 結果 4 Gitでバージョン管理、テキストなので差分管理も簡単! 4 エディタが軽いので作成が快適! 4 Outputからお目当ての章が見やすい!探しやすい! 4 Outputは、意外と営業の人に受けが良かった! 4 「え?なにこれ?なんてツール?あとで教えて」
  45. 45. 結論 4 競合ツールとの比較 4 ドキュメントを書くスピードは早いよ! 4 導入のためのあれこれ、または導入後の課題 4 「Sphinxで書いていく!」空気を作るのが難しい 4 個人的には、「仲間(賛同者)」がいてくれると助かる
  46. 46. 結論 4 メンバーにreSTを書いてもらうのが難しい 4 メリットの周知、慣例からの脱却までが長い 4 納品物にするにはちょっと課題が多いかも 4 今回解決の糸口は見つからず…

×