Read the Docsでコンパイルがうまくいかなかったのでローカル環境でデバッグした話

5084 ワード
documentation Sphinx Python ReadtheDocs Docker Python テキストリンク

tl;dr

  • Read the Docs (RTD)でよくわからないバグでコンパイルできない -> Dockerを使うと簡単にデバッグできるよ。

問題

  • RTDにはじめてドキュメンテーションを登録してみたところ、エラーでまくり。

やったこと

公式ドキュメンテーションにあるとおりRTDはそのドキュメンテーションビルド手順を完全に公開しています。また、ビルドに使う環境のdockerイメージも公開しているので、手元で同等の環境を作り、デバッグすることが容易です。

まず、dockerイメージをpullし、interactive shellで起動します。

docker run -it readthedocs/build:latest /bin/bash

ちなみに、本記事記載時は2.0のtagがlatestでした。

次に、管理画面のビルドログを元にコマンドを実行していきます。本来であれば公式のビルド方法をpythonから読み解いてもいいのですが、面倒なのでディレクトリ名などから適当に行間をうめつつ実行していきます。

export READTHEDOCS=1  # 追加分
mkdir -p /home/docs/checkouts/readthedocs.org/user_builds/word-embedding-loader/envs  # 追加分
git checkout https://github.com/koreyou/word_embedding_loader.git /home/docs/checkouts/readthedocs.org/user_builds/word-embedding-loader/envs/latest
cd /home/docs/checkouts/readthedocs.org/user_builds/word-embedding-loader/envs/latest  # 追加分

python2.7 -mvirtualenv --no-site-packages --no-download /home/docs/checkouts/readthedocs.org/user_builds/word-embedding-loader/envs/latest 
source /home/docs/checkouts/readthedocs.org/user_builds/word-embedding-loader/envs/latest/bin/activate  # 追加分
python /home/docs/checkouts/readthedocs.org/user_builds/word-embedding-loader/envs/latest/bin/pip install --use-wheel -U --cache-dir /home/docs/checkouts/readthedocs.org/user_builds/word-embedding-loader/.cache/pip sphinx==1.5.3 Pygments==2.2.0 setuptools==28.8.0 docutils==0.13.1 mkdocs==0.15.0 mock==1.0.1 pillow==2.6.1 readthedocs-sphinx-ext\<0.6 sphinx-rtd-theme\<0.3 alabaster\>=0.7,\<0.8,!=0.7.5 commonmark==0.5.4 recommonmark==0.4.0 
# requirements.txtのpathは自ら指定していないので、前処理としてrequirements.txtの場所を探してくれている模様
python /home/docs/checkouts/readthedocs.org/user_builds/word-embedding-loader/envs/latest/bin/pip install --exists-action=w --cache-dir /home/docs/checkouts/readthedocs.org/user_builds/word-embedding-loader/.cache/pip -r/home/docs/checkouts/readthedocs.org/user_builds/word-embedding-loader/checkouts/latest/requirements.txt
python setup.py install --force 

# 元は -b readthedocs になっていたが、動かないので定番のhtmlに変更
python /home/docs/checkouts/readthedocs.org/user_builds/word-embedding-loader/envs/latest/bin/sphinx-build -T -b html -d _build/doctrees-readthedocs -D language=en . _build/html

あとは問題がおきた手順のところで、python -m pdbなりなんなりしてデバッグしてください。

ちなみに、原因は余計な項目をPATHに加えていたからでした。(RTDはpython setup.py installを実行してくれるため、プロジェクトのパッケージディレクトリをPATHに加える必要はない)