読者です 読者をやめる 読者になる 読者になる

Sphinx (PDF 出力) を導入してみた

sphinx
注意
PDF 出力を前提とした話しになっています

OSS のドキュメントとしてはよく使われておりますが、実際に仕事の道具として導入してみた人はあまりいないのではないでしょうか。

導入のきっかけや、実際導入した際の環境などを書いて行ければと思います。

注意事項としては Sphinx を自分自身はまったく使いこなしていないので、Sphinx やそれらの「技術的」な話しは出来ません。そこを期待されている方は @aohta に「話しを聞きたい」とかリプライ飛ばすともしかすると書いてくれるかも知れません。

ドキュメントツール導入のきっかけ

もともと Word が使いづらく reST を自分個人で使い続けてました。使い始めたきっかけは @everes が使っていたからだったと記憶しております。一人でほそぼそと使っていましたが、rst2pdf がきっかけになって社内で使ってみたらどうか?という話が出てきました。ただ rst2pdf では色々限界があったので Sphinx に至っています。

導入自体は Sphinx がメインというわけではなく、PDF 出力が最大の目的でした。

ドキュメントツールへの条件

ドキュメントツールへの条件を明確にしておきたいと思います。

以下の3つがドキュメントツールへの条件でした。

  • テキストファイルであること
  • バージョン管理 (Subversion/Mercurial/Git など) 出来ること
  • PDF 出力が出来ること

そのため最初は reStructuredText + rst2pdf を使用して色々な場所で試したりしていました。

PDF の展開先

PDF にする対象は自社製品のマニュアルのため、展開先は身近な誰かではなく"安くないお金を出して買った製品購入者や導入者"です、かなりハードルは上がります。Word レベルでもかなり厳しいと感じていました。

rst2pdf の限界

Sphinx の導入は、rst2pdf の限界もありました。あまり覚えてないのですが @aohta から「rst2pdf はもう無理だから捨てよう」って言われたのがきっかけだったのかも知れません。

Sphinx(PDF 出力) 導入

正直上を説得するとかはありませんでした。もともと rst2pdf は採用されていましたし、幸運な事に現場の技術的判断がほとんどの面において自分で出来る位置だったので、自分が責任をとる前提で Sphinx の導入を推し進めました。

ドキュメントの Sphinx 化、つまり Sphinx から PDF を生成するという作業はそう簡単には進みませんでした。時間にして数ヶ月はがっつり取り組んで貰ってやっとこさスタートにたったと記憶しています。

このときはドキュメントツールの調査や作業などを @aohta や @itawasa が色々やってくれました。

pLaTeX 経由で素敵な出力にするまで数ヶ月かかったような気がしています。さらに 1 からドキュメントをごりごり書く機会もあったりして、試行錯誤が半年以上続いたと思います。

Sphinx(PDF 出力) 継続

Sphinx から pLaTex 経由での出力は、pLaTex の知識がある程度いるようで @aohta や @itawasa はそっちけいの本を色々読んだり、調べたりしていました。つまり PDF 出力を前提とする場合は Sphinx や reST の知識だけでは無く pLaTeX の知識も必要となってくるようです。

ちなみに、当たり前ではありますが、最新の Sphinx や Docutils に追従はしています。

Sphinx(PDF 出力) 発展

自分が携わる案件の納品用ドキュメントは全て Sphinx を採用しました。ただ、やはりまだまだ課題は沢山あるようで仕事の暇を見て色々試行錯誤しているようです。

また仕事柄 seqdiag がかなり嬉しいので、こちらも @tk0miya を呼んで「ここをこう修正してくれないと仕事で使えないから修正して」という無茶なお願いをしたりしました。

おかげで seqdiag も正式に仕事の道具として採用させて頂きました。この場を借りて改めて @tk0miya に感謝します。

Sphinx (HTML 出力)

追記
2012-01-07

社内で HTML 版をどの程度使っているのか考えると、そんなに使っていません。これはなぜか考えると github の reST プレビュー機能がかなり優秀なんですよね。Sphinx の用に体系的にまとめていく必要のある文章は外に出す文章が主で、社内は 1 つの情報は 1 つの reST ファイルで収まることがほとんどです。

ただ、定常的に見られる情報については github -> jenkins -> 社内サーバデプロイという流れをとってはいます。ただやはりその場で編集できないと定常的に見られる情報としては厳しいのかなぁと。

社内はの非技術者向け情報管理は結局 google sites に落ち着いてしまいました。

環境

ここで、導入環境を説明しておいた方がいいと思います。まずは今の環境を。

正直、かなり恵まれている環境だと思います。このメンバーでもかなり苦労しました。

メンバー
  • @aohta
    • ドキュメント全般をいじっていて Sphinx にもパッチを送っている
  • @itawasa
    • pLaTeX 周りを色々といじって Sphinx にもパッチを送っている
  • @shkumagai
    • Sphinx の有名テーマ作者、さらに reST についてもかなり明るい
スキル

全員が Git を使いこなし、github も使える。さらに reST に関しては誰も困らないくらい理解をしている。

ビルド

Jenkins が自動で Sphinx から PDF に変換してくれる、コミット事に自動でビルドしてくれる。

感想

注意
PDF 出力が必須の前提で書いてます

まず Sphinx は気軽な気持ちで導入するようなものではありません。ハッキリ言って Word で十分なら Word にすべきです。特に PDF となると導入しないほうがイイと思います。Word の置き換えとして検討するべき物では無いかなと思います。

もし導入したい場合は、仕事として Sphinx/pLaTeX に触れられる事、ドキュメントの大切さを理解している環境があること、バージョン管理が既に導入されていることが導入する条件の最低条件だと思います。

PDF 出力前提で書いていますが、メンテナンスする人やバグが出たときパッチを当てる人、まぁこの辺は OSS ですからその辺は割愛しますが、Word でいけるならできる限り Word で行くべきです。

また、Sphinx を導入したから全てがうまくいくわけで貼りません。銀の弾丸なんてないですし。そもそも Word でなぜ失敗したのかを考えるべきです。多くの場合はルールがなかったりすることの方が多いのでは無いでしょうか。

Sphinx を導入すればますますルール決めが重要になってきます。バージョン管理も含んできますし。

なので、Sphinx を "仕事" で使おうとしている人は、Word でダメな理由をしっかりと考える必要があると思います。

なんか、凄く否定してばかりですが、個人的には導入して大成功だと思っています。大きな投資をした分、ドキュメントのコストがかなり減りました。それもこれも @aohta や @itawasa のおかげなのですが。

追記
2012-01-07

書いた後色々な人に突っ込みを貰ったので、頭を冷やして考えてみたのですが、正直 HTML 出力だけの場合は社内に導入するメリットってあんまりない気がしました。

PDF 出力が出来る前提じゃないと Sphinx の導入はなかったという感想です。頻繁に更新する場合は wiki の方がいいでしょうし、マニュアルとして書くなら PDF 出力が欲しくなってくると思います。

ただテキストファイル + バージョン管理 + 統合という観点で行くのであれば導入は可能な気がしました。

ただ、今は git clone 出来る wiki とかあるので素直にそっちを使った方がいい気がしないでもないです。

結論

あくまで環境を考えてから導入を検討すること。Sphinx銀の弾丸ではありません。ただ上手く使えば凄く便利なツールです。使いたいから使うのでは無く、"維持を楽にする" や "コストが削減する" 等の現実的な目的をもって導入を検討しましょう。

追記
2012-01-07

PDF 出力を前提に導入するなら壁は高いですが導入に成功すればかなり良いです。ただ HTML のみの場合は wiki 等を検討してみた方がいいのかも知れません。wiki はドキュメントの統合管理という意味ではかなり便利ですし。

もちろん外部に Web で公開するドキュメントとしてであれば HTML だけでも全然ありだと思います。

社内で HTML 出力だけでも Sphinx 導入したらこんなに幸せになったよという話しはどなたか是非。