はじめに
こんにちは、Sphinx-Users.jpの賑やかし担当です。最近PHP界隈でも人気の高いドキュメント生成ツールSphinxですが、みなさん楽しいSphinxライフを送っていますでしょうか。さて、Sphinxでドキュメントを作った場合、一番キャッチーなのはHTMLだと思うんですが、そのホスティングはみなさんどうされていますか？
Sphinx-Users.jpにいくつかホスティングの方法を紹介してありますが、今日は割と新しいホスティング方法のReadTheDocsをご紹介します。
ReadTheDocsってなに？
ReadTheDocsは2010年のDjango Dashで作成されたコードを元に公開されているサービス/ライブラリです。外部に公開されているSphinxのレポジトリ（Git, Mercurial, Bazaar, Subversion）を指定すると、自動でビルドしてくれます。Webフックを使ってレポジトリが更新されるとビルドが走ってくれるのも嬉しい。
Python界のイケメン（池田麺太郎さん）こと@AE35(id:namaco35)が色々と調べてくれてますのでリンク貼ります。じゃーん。
さらに日本語訳もしてくれています。じゃじゃーん。麺太郎さんありがとう！
Webサービス ReadTheDocsの使い方
まずはドキュメントホスティングサービスとしてのReadTheDocsの使い方です。これは後で紹介するライブラリをAmazon EC2上で動かしているもので、無料でSphinx製ドキュメントをホスティングしてくれます。
既存のSphinxレポジトリのインポート
とってもシンプルで、使い方も簡単です。まずアカウントを取得して、ログインしてダッシュボードに行きます。
既存のSphinxプロジェクトをホスティングする場合はImportボタンを押して、こんな感じで設定します。とってもシンプルで分かりやすい。そして登録が終わったら一番下にあるCreateボタンを押します。
すると「いまビルドしてますよ」っていうメッセージが出ます。
再びダッシュボードにもどると新たにプロジェクトが出来ているので、それをクリックしてみるとView Docsというボタンがあります。
これを押すと、はい！ドキュメントが公開されています！すばらしい！あとはレポジトリをガンガン更新するだけですねー。ちなみにReadTheDocsではデフォルトのテーマがReadTheDocsオリジナルになっています。これもシンプルで見やすい。
新規ドキュメントの作成
さらにReadTheDocsはWikiのようにドキュメントを新規作成できます！（でもちょっと不安定）
ReadTheDocsを自前の環境で動かす
readthedocs.orgはサービスですが、ReadTheDocs自体はDjangoベースのSphinxホスティングアプリなので、ローカルサーバでも動かすことが出来ます。*1詳細なインストール方法に関しては公式ドキュメントに記載してあります。ここには本家と和訳へのリンクを貼っておきます。基本的にはドキュメントに書いてあるとおりにやれば環境が作成できます。
- http://read-the-docs.readthedocs.org/en/latest/install.html
- インストール — Read The Docs v0.1 documentation
Python実行環境の仮想化をするvirtualenvとそのサポートをするvirtualenvwrapperを使います。導入方法はここに書きました。
まずはReadTheDocs用環境rtdを作成し、GitHubよりプロジェクトをクローン。
% mkvirtualenv rtd New python executable in rtd/bin/python Installing setuptools............done. virtualenvwrapper.user_scripts Creating /home/ymotongpoo/.virtualenvs/rtd/bin/predeactivate virtualenvwrapper.user_scripts Creating /home/ymotongpoo/.virtualenvs/rtd/bin/postdeactivate virtualenvwrapper.user_scripts Creating /home/ymotongpoo/.virtualenvs/rtd/bin/preactivate virtualenvwrapper.user_scripts Creating /home/ymotongpoo/.virtualenvs/rtd/bin/postactivate virtualenvwrapper.user_scripts Creating /home/ymotongpoo/.virtualenvs/rtd/bin/get_env_details % mkdir rtd % cd rtd % git clone http://github.com/rtfd/readthedocs.org.git
次にReadTheDocsを動かすのに必要なライブラリをインストールします。必要なものはすべてプロジェクトレポジトリ内のpip形式でファイルに書いてあるのでpipを使ってインストールします。
% cd readthedocs.org % pip install -r pip_requirements.txt % pip install redis
依存パッケージのインストールが終わったらDjangoアプリケーションの初期化をします。
% cd readthedocs % ./manage.py syncdb Syncing... Creating tables ... Creating table auth_permission ... Creating table watching_pageview You just installed Django's auth system, which means you don't have any superusers defined. Would you like to create one now? (yes/no): yes Username (Leave blank to use 'ymotongpoo'): E-mail address: rtd@ymotongpoo.com Password: Password (again): Superuser created successfully. Installing custom SQL ... Installing indexes ... No fixtures found. Synced: > django.contrib.auth ... > rtd_tests Not synced (use migrations): - sentry - indexer - projects - core - builds - editor (use ./manage.py migrate to migrate these)
記載があるようにmigrateをします。
% ./manage.py migrate Running migrations for sentry: - Migrating forwards to 0009_auto__add_field_message_message_id. > sentry:0001_initial ... - Loading initial data for editor. No fixtures found.
さあ、これで準備が出来ました。早速起動してみます。*2
% ./manage.py runserver 0.0.0.0:8000 Validating models... 0 errors found Django version 1.3, using settings 'settings.sqlite' Development server is running at http://0.0.0.0:8000/ Quit the server with CONTROL-C.
動いたあああ！
早速ユーザーを作成して、ドキュメントを登録してみましょう。まずここが最初のはまりどころです。2011年06月27日現在のバージョンだと、ウェブの画面からではユーザ登録したときにエラーがでます。（メール周りが上手く動かない）そこでDjangoのadminを使ってユーザを登録します。/adminにアクセスしてUserの追加を行います。
作成したadminユーザでログイン。
Userのところで+ボタンをおし、適当なユーザを作成してSaveする。
とりあえずできたので、今度はアプリケーションのログイン画面へアクセスし、ログインする。
あとはWebサービスとして公開されてるReadTheDocsと同様にレポジトリを追加すれば完了です！（下記画像URLに注目。ローカルだよ。）
こんな感じでSphinx使ったドキュメント管理が簡単になるReadTheDocsを是非活用してみてください！
