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

2014/10/26 SphinxCon JP 2014

@kk_Ataka

自己紹介4 Twitter: @kk_Ataka

4 GitHub: gosyujin

4 普段いるところ4 Kawasaki.rb

4 Jekyllrb-ja(主催)

4 Python力4 文法もまだあやしい

発表の趣旨4 SIerでもSphinxを使いたいので職場で奮闘してみた備忘録4 利用事例4 拡張の紹介

4 Kawasaki.rbというイベントで話した内容の総集編4 できたこと、できなかったこと含めて駆け足で共有します4 主観が多め

今日話さないこと4 Sphinxとはなんぞや4 reST記法とはなんぞや4 Sphinxのインストール方法とか使い方とか

アジェンダ1. 競合ツールとの比較2. 導入のためのあれこれ、または導入後の課題3. 実際に導入してみた感想

競合ツールとの比較

競合ツールとの比較！4 導入するためには上の人を説得するための政治が必要…

4 競合ツールと比較してよさ気と思ったことを伝えていく1. Office(Word, Excel)

2. Wiki, Markdown

3. Sphinx

4 好きな言葉「適材適所」

比較1 Office

Office 長所4 SI界のスタンダード4 WYSIWYGな操作4 きめ細かいデザインが可能4 図やフローの挿入が容易

4 誰のPCにも入っていて、誰でも使える

!?

Office 短所4 あらゆるものがOfficeで作成され、至る所にちらかる4 日付バージョン管理…(主観)

4 恐怖の「 議事録_20140505_2(最新)(xx修正).xls 」4 検索性が非常に悪い4 違うシートとか、吹出しとか 非表示とか…探せない…

Office 短所4 diffが取るのがメンドくさい4 取れないとは言ってない、最近は取れるっぽい

4 ミリ単位のレイアウト修正を強いられる4 リストとかすぐ壊れる4 内容を集中して書かせて！

4 (職人芸が発揮されるほど)重い

番外Officeのいいところ…カット！

Officeのいいところ4 Officeでしかできないことも、ある4 過去資料でいいところあげてます！4 ようは適材適所でよろしくお願いします

比較2 Wiki, Markdown と Sphinx

Wiki, Markdown と Sphinx の長所Officeで短所として挙げた問題は解消できている！…と思う

Wiki, Markdown と Sphinx の長所> あらゆるものがOfficeで作成され、至る所にちらかる 問題4 プレーンテキストで作成される4 Officeよりは探しやすいんじゃないかと思うのだが…4 ブラウザ、エディタの検索とか、Wiki内検索とか

Wiki, Markdown と Sphinx の長所> diffが取るのがメンドくさい 問題4 Markdownはプレーンテキストなので簡単4 バージョン管理もしやすい

4 Wikiもだいたい差分表示機能あり4 diff取りやすい

Wiki, Markdown と Sphinx の長所> ミリ単位のレイアウト修正 問題4 出力先(html+css、pdfなど)である程度統一できる

Wiki, Markdown と Sphinx の短所Officeでは特に意識していなかったことを考慮する必要あり

Wiki, Markdown と Sphinx の短所4 記法を覚える必要がある4 未経験者にちょい敷居が高い…

4 「特定部分のみ」のレイアウト修正4 cssなどに独自の処理を入れなければならない

4 図やフローの挿入はタグで挿入4 直感的にいじれない(現物をD&D…)

Wiki, Markdown の短所4 検索性はあまりよくない4 しっかり作れば…

4 それでもOffice + 共有サーバコンボよりは…

4 重い4 体感としては Office > Wiki, Markdown > Sphinx

4 サーバ性能とか同時アクセス数によるけど

Sphinx だけの長所4 体系的なドキュメントの骨組みを簡単に整えられる 強力な機能がある4 この辺をサクッとよろしくやってくれているのが

doctree...である気がする(まだ未調査)

4 Wikiとかでこれを整備するのはちょっとしんどい

Sphinx だけの長所4 検索性はよいと思う4 体系的にまとまるため

4 軽い4 Outputが静的ファイル4 htmlをWebサーバに置けば静的ファイルを取ってくるのと変わらない

ここまでのまとめ4 慣れ親しんだOfficeから脱却したい、管理しやすい形式でドキュメント作成に挑戦してみよう4 ならば Wiki, Markdown か Sphinx だ！

4 TipsとかならWiki, Markdownでもいいけど、ドキュメントなのである程度体系的に管理したい4 体系的に管理するのが得意な Sphinx だ！

結論: 一回Sphinxチャレンジしてみましょう！

導入のためのあれこれ、または導入後の課題

導入するための壁1. 対プロジェクトメンバー(PM)に対して(布教)2. 対顧客に対して(納品)

壁1. 対PM

対PM 登場人物4 自分4 Sphinxを導入したい人、基本的になんでもやる

4 メンバー4 導入したSphinxを使ってほしい人

対PM 「自分」の仕事4 今回はreSTで進めることの明確な宣言とサポート4 一番大事4 これができないと負の成果物が生成される…

対PM 「自分」の仕事4 メンバーが「rstファイルを開いてドキュメント作成」に注力できる環境を作る1. sphinx-quickstartで下準備2. ドキュメント自体のアウトライン作成3. doctreeの作成

などなど

対PM 「自分」の仕事4 ビルド環境、デプロイ環境などもお膳立て4 ビルドはJenkinsなどで拾う4 デプロイはApacheにhtmlファイル配備とか(お手軽)

対PM 「メンバー」の仕事4 reST記法を覚えてもらう4 Markdown -> reST -> Outputという裏技もある

(Pandoc経由)

4 バージョン管理ツールとかの話は…割愛

対PM 課題4 ローカルPCでのプレビュー4 メンバーのPCにSphinxを入れてもらうのは厳しい…4 そうすると、確認できるのがサーバにプッシュした時のみになってしまう

4 ローカルで簡単にreSTプレビューできないだろうか…4 GitHubとか使えばある程度できるんだけど

対PM 課題4 プロジェクト(会社)の風土にあわせたカスタマイズが必要かも4 こういうレイアウトがいい4 こういうヘッダフッタがほしい4 こういう改訂履歴ページがほしい

対PM 課題4 今回は「変更履歴」出力プラグイン作ってみた4 sphinxcontrib-releasenotesプラグイン

4 .. releasenotes:: ディレクティブを追加したところにGitのコミットログと差分を貼り付け

4 Git使えない人用

壁2. 対顧客

対顧客 登場人物4 プロジェクト4 Sphinxでドキュメント納品する側

4 顧客 (社内の人 or 社外の人)

4 ドキュメントを納品される側4 歴史的経緯からOfficeで納品される事が多い4 例外はJavadocとか？

対顧客 「プロジェクト」側の仕事4 Sphinxで作成するドキュメントに関して「今回はOfficeじゃない形式で設計書とか書きますよ」の合意を得とく

対顧客 「顧客」側の仕事4 特になし？心構えくらい？

対顧客 課題4 納品形式 最重要(次ページ参照)

4 納品後 「誰が」 保守するのか4 顧客が巻取ってしまう場合、どう保守すればよいのか4 要解決事項、誰かどうやってるか教えてください…

4 これが解決できないと、Sphinxは納品対象外ドキュメントにしか適用できない…

実際に導入してみた感想

環境4 3ヶ月位のほぼ1人プロジェクトで「社内資料」をSphinx！4 社内資料なので、納品関係の課題はスルー4 環境揃えたい放題4 Git + Sphinx + Jenkins etc

4 途中で1人サポートに入ってもらった

結果4 Gitでバージョン管理、テキストなので差分管理も簡単！4 エディタが軽いので作成が快適！4 Outputからお目当ての章が見やすい！探しやすい！4 Outputは、意外と営業の人に受けが良かった！4 「え？なにこれ？なんてツール？あとで教えて」

結論4 競合ツールとの比較4 ドキュメントを書くスピードは早いよ！

4 導入のためのあれこれ、または導入後の課題4 「Sphinxで書いていく！」空気を作るのが難しい4 個人的には、「仲間(賛同者)」がいてくれると助かる

結論4 メンバーにreSTを書いてもらうのが難しい4 メリットの周知、慣例からの脱却までが長い

4 納品物にするにはちょっと課題が多いかも4 今回解決の糸口は見つからず…