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

YAMAGUCHI::weblog

土足で窓から失礼いたします。今日からあなたの息子になります。 当年とって92歳、下町の発明王、エジソンです。

ReadTheDocsでSphinxホスティングは磐石(になる予定)

Sphinx

はじめに

こんにちは、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レポジトリのインポート

とってもシンプルで、使い方も簡単です。まずアカウントを取得して、ログインしてダッシュボードに行きます。
f:id:ymotongpoo:20110310001941p:image
既存のSphinxプロジェクトをホスティングする場合はImportボタンを押して、こんな感じで設定します。とってもシンプルで分かりやすい。そして登録が終わったら一番下にあるCreateボタンを押します。
f:id:ymotongpoo:20110310001942p:image
すると「いまビルドしてますよ」っていうメッセージが出ます。
f:id:ymotongpoo:20110310001943p:image
再びダッシュボードにもどると新たにプロジェクトが出来ているので、それをクリックしてみるとView Docsというボタンがあります。
f:id:ymotongpoo:20110310001944p:image
これを押すと、はい!ドキュメントが公開されています!すばらしい!あとはレポジトリをガンガン更新するだけですねー。ちなみにReadTheDocsではデフォルトのテーマがReadTheDocsオリジナルになっています。これもシンプルで見やすい。
f:id:ymotongpoo:20110310001945p:image

新規ドキュメントの作成

さらにReadTheDocsはWikiのようにドキュメントを新規作成できます!(でもちょっと不安定)

ReadTheDocsを自前の環境で動かす

readthedocs.orgはサービスですが、ReadTheDocs自体はDjangoベースのSphinxホスティングアプリなので、ローカルサーバでも動かすことが出来ます。*1詳細なインストール方法に関しては公式ドキュメントに記載してあります。ここには本家と和訳へのリンクを貼っておきます。基本的にはドキュメントに書いてあるとおりにやれば環境が作成できます。

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.

動いたあああ!
f:id:ymotongpoo:20110501212819p:image
早速ユーザーを作成して、ドキュメントを登録してみましょう。まずここが最初のはまりどころです。2011年06月27日現在のバージョンだと、ウェブの画面からではユーザ登録したときにエラーがでます。(メール周りが上手く動かない)そこでDjangoのadminを使ってユーザを登録します。/adminにアクセスしてUserの追加を行います。
作成したadminユーザでログイン。
f:id:ymotongpoo:20110627221259p:image
Userのところで+ボタンをおし、適当なユーザを作成してSaveする。
f:id:ymotongpoo:20110627221300p:image
f:id:ymotongpoo:20110627221547p:image
とりあえずできたので、今度はアプリケーションのログイン画面へアクセスし、ログインする。
f:id:ymotongpoo:20110627221549p:image
f:id:ymotongpoo:20110627221550p:image
あとはWebサービスとして公開されてるReadTheDocsと同様にレポジトリを追加すれば完了です!(下記画像URLに注目。ローカルだよ。)
f:id:ymotongpoo:20110627221551p:image

こんな感じでSphinx使ったドキュメント管理が簡単になるReadTheDocsを是非活用してみてください!

*1:ただしまだ結構開発途中なのでどんどんテスターになってバグ登録に協力しましょう!

*2:普通にオプションなしで起動するとlocalhostでしか接続できないという罠にはまった。俺ダサい。