ローカルリポジトリでRead the Docs使ってみた
なぜ使おうと思ったのか
業務に関連するドキュメントをSphinxで書いてみたいと思ったけど、使えるマシンでは既にapache立ち上がってたりまあいろいろ面倒な事情があった。
で、Read the Docsとかいうのはローカルにインストールして使えたなあというのと、Djangoアプリケーションだからそのままhttpサーバにもなるし、結構手軽なんじゃないかと思ってやってみた。
ちなみにRead the Docsの事を知ったのはこの記事から。
http://d.hatena.ne.jp/ymotongpoo/20110627/1309181077
Read the Docsインストール
インストールはここに従ってやった。
http://readthedocs.org/docs/readthedocs-doc-ja/en/latest/index.html
virtualenvで環境を切る。
mkvirtualenv --python=python2.6 --distribute docs mkdir docs cd docs
gitからコードを持ってきてパッケージのインストール。
git clone http://github.com/rtfd/readthedocs.org.git cd readthedocs.org pip install mercurial pip install -r pip_requirements.txt
Djangoでごにょごにょ（よくわかってない）
cd readthedocs ./manage.py syncdb ./manage.py migrate ./manage.py runserver 0.0.0.0:8000
これでこのサーバのポート8000にアクセスしたらちゃんと表示された。
躓いたところ
pythonにsslモジュールが無くて、pip_requirements.txtの中のhgの処理の途中でコケていたこと。
ソースからコンパイルした奴なんだけど、インストール先のサーバではlibとかincludeを独自の場所に置いていた所為でライブラリ読めずにssl無効でコンパイルされていたみたい。
ちゃんとopensslとかインストールされている環境で普通にコンパイルすれば起きないと思う。
mercurialは先にインストールしておかないと失敗するぽい？
BeautifulSoupは4.0bがインストールされたが、syncdb打った時にimport失敗していた。バージョン変えたら通った。
pip uninstall BeautifulSoup pip install BeautifulSoup==3.2.0
リポジトリ作成
適当にディレクトリ掘ってhg init。Sphinxのプロジェクト作ってリポジトリに突っ込む。
cd docs mkdir repos hg init sphinx-quickstart hg add ./* hg commit -m 'init files'
リポジトリのインポート
あとは画面からインポートするときに「Repo:」にローカルリポジトリのフルパスを指定すればOK。
一応ビルドは出来たんだけど、エラーが出ていたのがちょっと気になる。原因はまだ調べてない。
ビルド時の出力
Building test
Lock (test): Lock aquired
(snip...)
Running: 'sphinx-build -b html . _build/html'
Copying docs on the local filesystem
Running: 'sphinx-build -b latex -d _build/doctrees . _build/latex'
Running: 'pdflatex -interaction=nonstopmode test.tex'
Command failed: Traceback (most recent call last):
File "/home/inoshiro/dev/docs/readthedocs.org/readthedocs/projects/utils.py", line 48, in run
env=environment)
File "/usr/lib/python2.6/subprocess.py", line 623, in __init__
errread, errwrite)
File "/usr/lib/python2.6/subprocess.py", line 1141, in _execute_child
raise child_exception
OSError: [Errno 2] No such file or directory
Running: 'sphinx-build -b man . _build/man'
Running: 'mv -f /home/inoshiro/dev/docs/readthedocs.org/user_builds/test/checkouts/latest/_build/man/*.1 /home/inoshiro/dev/docs/readthedocs.org/media/man/test
/latest/test.1'
Running: 'sphinx-build -b epub . _build/epub'
Running: 'mv -f /home/inoshiro/dev/docs/readthedocs.org/user_builds/test/checkouts/latest/_build/epub/*.epub /home/inoshiro/dev/docs/readthedocs.org/media/epub
/test/latest/test.epub'
HTML Build OK
*** Failed updating modindex: Error 111 connecting localhost:6379. Connection refused.
*** Failed updating genindex: Error 111 connecting localhost:6379. Connection refused.
*** Failed updating search: Error 111 connecting localhost:6379. Connection refused.
Purged Version of test (1)
Lock (test): Releasingindexが作れてないっぽい。検索も出来ない？まあ、ドキュメント量はそんなに多くないので問題はないけど。
あと、themeはRead the Docsのものよりも、natureとかの方が見出しが見やすくて好き。
