これは Sphinx Advent Calendar 2012 6日目です。@togakushi さんから受け取りました。
@togakushi さんのテーマに関するテーマ（私の表現がアレですね..）を今後参考にしながら社内のsphinxサイトをリニューアルしたいなと思う今日この頃です。
さて、@goingmywaynet です。Python使えない自称エンジニア（本業は事務屋）ですが、面白くてSphinxを利用させて頂いています。ネタの使い回しになりますが、ちょっと変わった Sphinx の使い方のご紹介です。 Tipsや技術的な内容は薄いと思いますが、お付き合い頂ければと思います。
１．Sphinx とは
Advent Calendar からこられた方には説明の必要はないと思いますが、Sphinxは元々は Python というプログラミング言語のメンテナンスやAPIのためのドキュメントを作成するツール(ドキュメントツール）でした。私が興味深いと思う以下の様な特徴があります。
- クロスリファレンス機能
- toctreeによるドキュメントの階層化
- 複数の出力フォーマットを一つのソースで（ HTML , PDF , ePUB , etc..)
- 日本ユーザーグループがある
コードハイライト機能やBlockdiagなどの多彩な機能やアドインがあることから、主にエンジニアの間でドキュメントを書く為のツールとして活用されてますが、これを非エンジニアの領域で使ってみました。
２．Sphinxの活用環境と動機
windows 端末と windows共有フォルダ が組まれたごくごく一般的な事務屋さんの環境において、私たちは以下の様な課題を抱えていました。
- 共有フォルダがカオス（「新しいフォルダ〜コピー」「新○○」「New○○」..）
- 情報が分散（紙、doc、xls、PDF、誰かの頭の中.. )
- 情報の出自がバラバラ（課内文書、社内文書、社外文書、色々なクリップ）
- 書式が統一されていない（まあ、いろいろ書き方有るよね..）
- 経緯がわからない。結論が分からない。更新されない。
ちなみに、”マニュアル”という名の「何となく判るけど、実施するには情報が足りないモノ」をかなり目にしてきました。（特にQMSとかISOとかで作らされる資料に多い気がする）
さらに、人的環境として以下の様な課題を抱えていました
- 人は異動するもの
- 技術継承は OJT! OJT! OJT!
- ノウハウを最も持っている者から離れていく
- ある日、中心人物が食中毒になったら業務が止まる
そこで、各人が自分の資料やPCや脳裏や共有フォルダの奥深くに溜め込んだ情報やノウハウを手軽に洗い出し、その情報を集約／整理する環境を必要としていました。( ちなみに、運用ドキュメントにおけるsphinxの可能性については @tcsh さんの Operation Document Model がとてもとても参考になります )
ただし、
- 文書管理システムとか導入するのも管理するのもめんどい
- 滅多にない作業やすでに終わった仕事の手順書とか書くの面倒いし頼み難い
- 決済書類とか書くのめんどい
- すでにある情報を決まった形式に書き換えるのめんどい
- 情シス部門じゃないので Admin 権限もってない
ということで、制約の中で出来る限りの事をしようということで、Sphinxを活用して情報の整理に取り組んでいます。（これを仮に Knowledge Base と呼びます）
利用者も、”make html” とかコマンドを叩く事にすら抵抗がある（の割りには Microsoft Word / Excel / PowerPoint なら使いこなす）メンバーが多いので、とにかく簡単に情報を集約できる仕組みを目指しました。
３．Sphinx による仕組み
Sphinx を活用して、共有フォルダに分散している、各種情報に対するインデックを持つWebページを作ってしまう事にしました。機能的にはざっくり以下の様な通りです
- 特定Window共有フォルダ配下を再帰検索
- 指定のファイル名（アンカーファイル）を見つけたらそのファイルを.rstとして扱う（もちろん、アンカーファイルは reST 形式で記述）
- SphinxでHTMLを生成する際にアンカーファイルの有ったディレクトリへのリンクを自動挿入（実際は.rstファイル生成時に記述している）
- 上記の繰り返しで、共有フォルダ内の必要な情報（のインデックス）をHTMLに集約していく
- sphinx のお陰でHTML内での検索も可能
生成されるHTML / ここから各種情報へ辿れる
各情報へのリンクは自動で生成
ここでいう「アンカーファイル」とは特定のファイル名を持つSJISのCR/LF改行コードファイルです。課員には自分の持つ情報について、
- 共有フォルダに既にあるものについては、そこに「アンカーファイル」を置いて、ざっくり（数行の）概要を書いてもらう。
- 頭の中にある情報についても、適当なフォルダに「アンカーファイル」を置いて、そのファイルにreSTで情報を記述してもらう。
という対応をお願いすることで、情報やノウハウの集約をし、一覧性を持たせたり、整理することが出来る様になるのでは無いかと期待しています。
４．仕組みを実現するために
アンカーファイルを検索し、.rst化し、sphinxでビルドする為のスクリプトを作成しました。また、日本語検索のためにMeCABも合わせて導入しています。これらの詳細については以下のリンクをご覧下さい。（使い回し .. 汗)
５．状況と今後の課題
実はすでに半年ほどこのSphinxによる情報整理に取り組んでおります 。事務屋さんな環境において、以下の様な状況になっております。
- 今まで個人資料だったものが集約されて、結構な数 のページが生成されている
- いまも週に数ページのペースで増えている
- だんだんと reST 記法が浸透してきている
- 足りない機能が出てきた
- たとえば、.. figure:: の画像ファイル添付などは.rst に変換後にファイルを移動してしまうためにリンクが切れてしまう
- 検索機能は期待したほど助けになってない
- MeCABのユーザ辞書を活用しているが、どうも英数字周りが弱い
- ページ内検索と検索ツールを併用してどうにか見つかる程度
とりあえず、来年まで活用を続けてみて、なにか良い結果になればと思っております。
さて、明日は @takanori さんです。