ReadTheDocsで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)が色々と調べてくれてますのでリンク貼ります。じゃーん。

ae35 / docs / source — Bitbucket

さらに日本語訳もしてくれています。じゃじゃーん。麺太郎さんありがとう！

Read The Docs ドキュメント — Read The Docs v0.1 documentation

Webサービス ReadTheDocsの使い方

まずはドキュメントホスティングサービスとしてのReadTheDocsの使い方です。これは後で紹介するライブラリをAmazon EC2上で動かしているもので、無料でSphinx製ドキュメントをホスティングしてくれます。

既存のSphinxレポジトリのインポート

とってもシンプルで、使い方も簡単です。まずアカウントを取得して、ログインしてダッシュボードに行きます。

既存のSphinxプロジェクトをホスティングする場合はImportボタンを押して、こんな感じで設定します。とってもシンプルで分かりやすい。そして登録が終わったら一番下にあるCreateボタンを押します。

すると「いまビルドしてますよ」っていうメッセージが出ます。

再びダッシュボードにもどると新たにプロジェクトが出来ているので、それをクリックしてみるとView Docsというボタンがあります。

これを押すと、はい！ドキュメントが公開されています！すばらしい！あとはレポジトリをガンガン更新するだけですねー。ちなみにReadTheDocsではデフォルトのテーマがReadTheDocsオリジナルになっています。これもシンプルで見やすい。

新規ドキュメントの作成

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

ReadTheDocsを自前の環境で動かす

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

Python実行環境の仮想化をするvirtualenvとそのサポートをするvirtualenvwrapperを使います。導入方法はここに書きました。

virutualenvとvirtualenvwrapperとpipを使う - YAMAGUCHI::weblog

まずは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ユーザでログイン。