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

ローカルリポジトリでRead the Docs使ってみた

Python Sphinx 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にアクセスしたらちゃんと表示された。

躓いたところ

pythonsslモジュールが無くて、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。
f:id:inoshirou:20110817013434p:image:w640
一応ビルドは出来たんだけど、エラーが出ていたのがちょっと気になる。原因はまだ調べてない。

ビルド時の出力

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): Releasing

indexが作れてないっぽい。検索も出来ない?まあ、ドキュメント量はそんなに多くないので問題はないけど。

あと、themeはRead the Docsのものよりも、natureとかの方が見出しが見やすくて好き。