Help us understand the problem. What is going on with this article?

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

More than 3 years have passed since last update.

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に加える必要はない)

koreyou
自然言語処理、応用機械学習、ロボットに興味がある企業リサーチャーです。 載せているコードは他に表記がなければThe UnlicenseとCC-0のデュアルライセンスにて公開しています。 発言は個人の見解であって所属組織を代表するものではありません。
Why not register and get more from Qiita?
  1. We will deliver articles that match you
    By following users and tags, you can catch up information on technical fields that you are interested in as a whole
  2. you can read useful information later efficiently
    By "stocking" the articles you like, you can search right away