Twisted Mind

商用サイトに Sphinx を導入してみた

sphinx

商用の製品紹介サイトに Sphinx を導入した事について書いてみます。

結論

とりあえずの結論

• 非技術者でも HTML を知らずに気軽に更新できる
• うまくテンプレート化されているのでページ追加が簡単
• 静的 HTML なのでリリースが簡単
• 結局画像の修正が大変
• 文章中心のサイトじゃないと意味が無い
• 非技術者が Windows/Git という組み合わせを覚える必要がある
• 枠組みをデザイナに作ってもらえれば、社内で色々好き勝手にいじれる

導入

製品の紹介サイトを作るというプロジェクトがありました。今までは CMS 等を使ってきていたのですが、今回は思い切って Sphinx を導入することにしてみました。

Sphinx のテーマを作ってもらえれば自社内で更新が気軽に出来るし、メンテナンスコストも低くなると考えたからです。

まず、社内に Web デザイナがいないため、誰かに白羽の矢を立てる必要がありました。ここは以前から交流があった @kinofumi に無茶を前提でお願いすることにしました。

Web デザイナにお願いしたこと

• Sphinx のテーマを作って貰う
• 最低限のドキュメントを流し込んだ状態で文章の見え方を整えて貰う

この二点です。正直 Jinja2 までゴリゴリ使っていただけるとは思っていませんでしたが、結果的にはかなり奥まで突っ込んで作って貰いました。

また、 @aohta がその過程で Sphinx の拡張プラグインを作ったりもしてました。

やりたかったこと

一番は、製品の魅力を伝えるのは非技術者です。つまり営業、広報等です。ただ、その場合は HTML や CSS の知識が前提になったり、CMS を建てたりとかなりハードルが上がってきてしまいます。

自分がやりたかったのは、営業が気軽に「文章作業」だけに没頭できる環境でした。

Sphinx はその点、文章の構成に集中出来ます。これはかなり大きいと思います。

ちなみに "おされなサイトを作るのが目的では無い" これは重要なポイントですね。

実際に出来たこと

非技術者が気になったところを簡単に修正できた

非技術者に一番壁だったのは、正直 Sphinx というより Git でした ... 。ただ Commit/Push/Pull だけ教えたらある程度理解してくれました。

reST は、ベース部分の文章は非技術者に Word で書いてもらったものを、技術者がまずは流し込んで構成だけ確認する。あとは日本語の修正等は非技術者で行ってもらえました。

テーマの修正を社内で気軽で出来る様になった

またテーマ自体を作成してもらったため、CSS を少しいじればかなり融通が効く状態になりました。また @shkumagai のような Sphinx のテーマ作成技術に熟知している人が身近にいたため、かなり対応が楽でした。

リリースが簡単

リリースは今回 AWS の S3 のウェブホスティング機能を使用してデプロイする予定です。リージョンを Tokyo にすればかなり早いし、メンテナンスコストがかなり低いです。DNS の設定だけでした。

金額的にもかなり低く抑えられるんじゃないかと考えています。

決まってからが早かった

デザインが決まるまで色々試行錯誤してましたが、デザインが決まってからはかなり早かったです。これはもちろん Web デザインを担当してくれた @kinofumi の実力がほとんどなのですが Sphinx のシンプルさというのも少しは影響したかなと。

そうそう、@kinofumi が今回の話しを書いてくれるようですので、期待ですね。

感想

実はデザインの確定に時間がかかって Sphinx 関連は二の次だったのですが ... 、かなり満足のいく物が出来たと感じています。HTML はいじっていませんし、文章を追加/修正するのも全て reST で書くだけです。

おしゃれなサイトでバーンと何かアピールするのには向いていませんが、商品を説明して理解して貰うサイトを作るにはかなりいいかなと感じました。

ただ、jinja2 で Sphinx テーマを作ってくれる Web デザイナさんはその辺にいるわけではないですし、これまた壁が高いと言えば高いかも知れませんね。

ここで、これが Sphinx で作った商用のサイトだ！って紹介したいところですが ... まだリリースが終わってないのでお待ち下さい。

今回は @kinofumi と初めて仕事させていただいたのですが、とても楽しかったです。 Sphinx で Web サイト作りに興味がある方は是非相談してみるとイイと思いますよ。

追記

リリースしました。

http://fullflex.accense.com/sg/

Permalink | コメント(0) | トラックバック(0) | 01:33

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

sphinx

注意

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

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

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

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

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

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

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

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

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

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

• テキストファイルであること
• バージョン管理 (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 導入したらこんなに幸せになったよという話しはどなたか是非。

Permalink | コメント(0) | トラックバック(0) | 00:47