何かの社内用ドキュメントの作成や、マニュアル、翻訳、書籍作成などなど、ドキュメンテーション用のツールとして注目を浴びてきている Sphinx ( スフィンクス ) 。そんな Sphinx をインストールして、みんなで触ってみよう！という ハンズオン 第3回が2月22日(水)に開催されたので、行ってきました。場所はタイムインターメディアさんの会議室。会場は市ヶ谷の防衛省にとても近いんですね。
◆いざ、ハンズオンへ！
どうして、このハンズオンに参加しようかと思ったかと言いますと、
- 社内用テキストエディタで書かれたドキュメント（という名のメモ書き）をキレイにしたい
- 某ドキュメントの翻訳用途で、割と手軽にドキュメントを整形したい
という、割と身近な問題を解決したかったから。
べっ、別にテキストや Wiki でも良いのですが、あとから見返す時にフォルダにテキストが散乱し、”文章が散らばり過ぎだろ、常識的に考えて(´･ω･`)”というシーンや、とにかく整理されていない”美しくないな”という状況と決別すべく、Sphinx に挑みました。
実は、前々からスフィンクスに興味は有りました。けれど、言語がPython だし大丈夫なのかな、という不安が少々ありました。環境構築が大変じゃないかな、あと、設定が面倒そう。というか、どこからどう始めていいのか分からない（´・ω・｀） …という状況。
そんな時、ハンズオンの情報を IT 勉強会カレンダーで発見し、早速登録→参加に至ったわけです。でも、ごめんなさい、どちらかというと、正直「きっかけ」がなくて「面倒そう」だったからです(;´Д`)。食わず嫌いでした。こんな、不甲斐ない自分が許せません（！）。
Sphinx は Python 言語でかかれたドキュメンテーション（文章作成支援）ツールで、Phtyon 界隈を中心とし、最近は色々なプロジェクトでも採用が進んでいるようです。また、ユニークなのは HTML 形式のページだけでなく、man 形式のファイルや、PDF 作成、果ては EPUB 形式など、多彩なアウトプットが可能な点があげられます。
◆インストール
さて、ハンズオンに先駈けて、当日午後になり慌てて Sphinx をインストールしていた愚か者はワタクシになります。まさに、ハンズオンに参加するからこそ、ようやくインストールに至りました。いや、だって、こうやって自分を追い込まないと、動機付けに至りません（苦しい言い訳）。
インストール方法は、ユーザ会のページに掲載されています。Windows , MacOS, Linux と、それぞれインストール可能です（お隣さんは、果敢にも OpenIndiana 環境上で Sphinx のインストールに挑まれていました）。
ちなみに、僕の Red Hat Enterprise 5 (i386) の環境でも、ちゃんと Sphinx を入れることが出来ました。Red Hat 社から Sphinx パッケージは提供されていませんが、Fedora Project 有志による EPEL (Extra Packages for Enterprise Linux) リポジトリでは、バッチリ配付されてました。お陰で比較的に入れることが出来ています。
僕の環境では、標準の python 環境で足りないものを、いくつか yum で入れました。
# yum -y install python-setuptools python-imaging
次に、EPEL から RPM ファイルの取得、インストールです。
# wget http://dl.fedoraproject.org/pub/epel/5/i386/python-sphinx10-1.0.4-3.el5.noarch.rpm # wget http://dl.fedoraproject.org/pub/epel/5/i386/python-sphinx10-doc-1.0.4-3.el5.noarch.rpm # wget http://dl.fedoraproject.org/pub/epel/5/i386/python-jinja2-2.2.1-1.el5.i386.rpm # wget http://dl.fedoraproject.org/pub/epel/5/i386/python-docutils-0.5-3.el5.noarch.rpm # wget http://dl.fedoraproject.org/pub/epel/5/i386/python-pygments-1.4-3.el5.noarch.rpm # wget http://dl.fedoraproject.org/pub/epel/5/i386/python-babel-0.9.5-2.el5.noarch.rpm # rpm -ivh * 警告: python-babel-0.9.5-2.el5.noarch.rpm: ヘッダ V3 DSA signature: NOKEY, key ID 217521f6 準備中... ########################################### [100%] 1:python-pygments ########################################### [ 17%] 2:python-docutils ########################################### [ 33%] 3:python-babel ########################################### [ 50%] 4:python-jinja2 ########################################### [ 67%] 5:python-sphinx10 ########################################### [ 83%] 6:python-sphinx10-doc ########################################### [100%]
そして、最後にシンボリック・リンクを作成します（これをしないと、make html できないです）。
# ln -s /usr/bin/sphinx-1.0-build /usr/bin/sphinx-build # ln -s /usr/bin/sphinx-1.0-autogen /usr/bin/sphinx-autogen
あとは、もう１つリンクを作成しておきます。
# ln -s /usr/bin/sphinx-1.0-quickstart /usr/bin/sphinx-quickstart
これで準備 OK です。
◆ハンズオンに参加！
ハンズオンに最終的に参加されたのは13名ぐらいだったのかな。スタート後は、ざっくりと概要説明の後、quickstart のデモ。「まずは sphinx-quickstart で、新規プロジェクトを作成する」事が全てのキモでした。あとは index.このあたりの手順は、ユーザ会のページに詳しく掲載されています。
プロジェクトを作る :: ドキュメンテーションツール スフィンクス Sphinx-users.jp
http://sphinx-users.jp/gettingstarted/make_project.html
ちなみに、会場では参加した方の全員が、予め Sphinx インストール済みという、気合いの入った状態!! デモのあとは、２チームに別れて、課題に取り組みました。課題は、第1回のレジュメ（印刷済み）を元に、自分で色々試してみる、というもの。分からない所は講師の方に教えていただいたり、まわりでお互いに教えあったりしていました（僕は尤も教わるほう中心でしたががが）。
で、僕も見よう見まねでドキュメントを検索しながら、なんとかページを作成できました。初めてのページが、こんなの。最終的にはレジュメっぽいものも、一応作成できました。おおよそ、正味1時間半で、なんとか作れるかなぁという所まで到達。今後は、まだまだディレクティブを覚えたり、何度も書いて慣れることが必要かな、と考えています。
ハンズオンに参加した印象としては、Sphinx は簡単！ というのが、僕の感想。TeX ほど敷居も高くなく、普段から Wiki を使い慣れている方であれば、比較的簡単に導入できるんじゃないかな、と思います。皆さんも機会があれば、是非チャレンジしてみると、いろいろ憚ると思います（ ＾ω＾）
最後になりますが、このような素敵な機会を設けられた、Sphinx-Users.jp および講師のみなさん、ありがとうございました!! 独学では、おそらくもっと多くの時間＆遠回りが必要だったに違いありません。そして、参加された皆さんも、お疲れ様でした!!
◆Reference
Sphinx ハンズオン #3 : ATND
http://atnd.org/events/25060
Sphinx-Users.jp :: ドキュメンテーションツール スフィンクス Sphinx-users.jp
http://sphinx-users.jp/index.html
reStructuredText入門 — Sphinx v1.0.6 documentation
http://sphinx-users.jp/doc10/rest.html
twitterのハッシュタグ #sphinxjp
