Install Sphinx from source on Linux

Introduction

職場のソースコードの文書化システムとしてSphinxがどんなものか試すことになり，まずはインストールする必要があった。

Pythonは3.4からパッケージマネージャーのpipが標準で付属しており，通常であればこれを使えば簡単にSphinxをインストールできる。

pip install --user sphinx

ただし，pipは不足している依存関係をWebからダウンロードしようとするので，インターネットと繋がっていなければこの手段は使えない。今回は職場のインターネットに繋がっていないマシンにインストールしてみたかったので，この方法ではだめだ。そこで，インターネットに繋がるマシンで必要な依存関係を自分でダウンロードして，インストールしたいマシンにtar.gzを配置する。そこで，tar.gzに対してpipを実行することでインストールする。

必要な依存関係はパッケージのsetup.pyのrequires変数に書かれている。これをみると，Sphinxの依存関係は以下であることがわかる。

requires = [
    'six>=1.4',
    'Jinja2>=2.3',
    'Pygments>=2.0',
    'docutils>=0.11',
    'snowballstemmer>=1.1',
    'babel>=1.3,!=2.0',
    'alabaster>=0.7,<0.8',
    'imagesize',
    'requests',
]

さらに，これらの依存関係に存在するパッケージが以下に示す依存関係を必要とする。

babel

pytz

jinja

markupsafe

全部のパッケージを手動でsetup.pyからインストールするのは面倒なので，以下の手順でpipでインストールする。

1. 最初にpipをソースからインストール
2. 残りのSphinxの依存関係はpipでソースファイルからインストール

pipの依存関係はsetupttoolsである。これらを整理すると，以下の順番でインストールを行うこととなる。

1. ソースのsetup.pyからpipをインストール
   1. setuptools
   2. pip
2. Sphixの依存関係をpipでインストール
   
   1. pytz, markupsafe
   2. その他（six, Jinja2, Pygments, docutils, snowballstemmer, babe, alabaster, imagesize,requests）
   3. Sphinx

Download all dependencies

依存関係を手作業で全てダウンロードするのは面倒なのでwgetでのダウンロードコードを以下に掲載する。

bash
LOCAL="$HOME/.local"
GET="wget -nc"
mkdir -p "$LOCAL/src/python"
cd "$LOCAL/src/python"

## For pip
$GET https://pypi.python.org/packages/6b/dd/a7de8caeeffab76bacf56972b3f090c12e0ae6932245abbce706690a6436/setuptools-28.3.0.tar.gz
$GET https://pypi.python.org/packages/e7/a8/7556133689add8d1a54c0b14aeff0acb03c64707ce100ecd53934da1aa13/pip-8.1.2.tar.gz

## For Sphinx
$GET 'https://pypi.python.org/packages/1f/f6/e54a7aad73e35232356103771ae76306dadd8546b024c646fbe75135571c/Sphinx-1.4.8.tar.gz#md5=5ec718a4855917e149498bba91b74e67'

$GET 'https://pypi.python.org/packages/53/35/6376f58fb82ce69e2c113ca0ebe5c0f69b20f006e184bcc238a6007f4bdb/pytz-2016.7.tar.bz2#md5=8d8121d619a43cf0b38a4195de1cb8a5'
$GET 'https://pypi.python.org/packages/c0/41/bae1254e0396c0cc8cf1751cb7d9afc90a602353695af5952530482c963f/MarkupSafe-0.23.tar.gz#md5=f5ab3deee4c37cd6a922fb81e730da6e'

$GET 'https://pypi.python.org/packages/b3/b2/238e2590826bfdd113244a40d9d3eb26918bd798fc187e2360a8367068db/six-1.10.0.tar.gz#md5=34eed507548117b2ab523ab14b2f8b55'
$GET 'https://pypi.python.org/packages/f2/2f/0b98b06a345a761bec91a079ccae392d282690c2d8272e708f4d10829e22/Jinja2-2.8.tar.gz#md5=edb51693fe22c53cee5403775c71a99e'
$GET 'https://pypi.python.org/packages/b8/67/ab177979be1c81bc99c8d0592ef22d547e70bb4c6815c383286ed5dec504/Pygments-2.1.3.tar.gz#md5=ed3fba2467c8afcda4d317e4ef2c6150'
$GET 'https://pypi.python.org/packages/37/38/ceda70135b9144d84884ae2fc5886c6baac4edea39550f28bcd144c1234d/docutils-0.12.tar.gz#md5=4622263b62c5c771c03502afa3157768'
$GET 'https://pypi.python.org/packages/20/6b/d2a7cb176d4d664d94a6debf52cd8dbae1f7203c8e42426daa077051d59c/snowballstemmer-1.2.1.tar.gz#md5=643b019667a708a922172e33a99bf2fa'
$GET 'https://pypi.python.org/packages/6e/96/ba2a2462ed25ca0e651fb7b66e7080f5315f91425a07ea5b34d7c870c114/Babel-2.3.4.tar.gz#md5=afa20bc55b0e991833030129ad498f35'
$GET 'https://pypi.python.org/packages/71/c3/70da7d8ac18a4f4c502887bd2549e05745fa403e2cd9d06a8a9910a762bc/alabaster-0.7.9.tar.gz#md5=b29646a8bbe7aa52830375b7d17b5d7a'
$GET 'https://pypi.python.org/packages/53/72/6c6f1e787d9cab2cc733cf042f125abec07209a58308831c9f292504e826/imagesize-0.7.1.tar.gz#md5=976148283286a6ba5f69b0f81aef8052'
$GET 'https://pypi.python.org/packages/2e/ad/e627446492cc374c284e82381215dcd9a0a87c4f6e90e9789afefe6da0ad/requests-2.11.1.tar.gz#md5=ad5f9c47b5c5dfdb28363ad7546b0763'

Install setuptools and pip

まず，setuptoolsとpipをソースのsetup.pyからインストールする。setup.pyからインストールするときは，インストール先にPYTHONPATHに設定されているディレクトリを指定しなければエラーとなる。PEP 370によれば，Unixでは~/.local/lib/pythonX.X/site-packages（X.Xはバージョン）が既定で指定されているので，事前にこのディレクトリを用意しておけばよい。なお，この場所が気に入らなければ，PYTHONUSERBASE環境変数に値を指定することで，~/.localの部分を変更できる。

現在のPythonのバージョンをシェルスクリプトのワンライナーで変数に取得してディレクトリを作成しておく。

PYTHONVERSION=$(python -V 2>&1 | grep -E -o '[0-9]+\.[0-9]+')  # Get python version
mkdir -p ~/.local/lib/python$PYTHONVERSION/site-packages

そして，stuptoolsとpipを順番にインストールする。

## setuptools
cd $LOCAL/src/python
tar xf setuptools-*.tar.gz
cd setuptools-*
python setup.py install --prefix=$LOCAL

## pip
cd $LOCAL/src/python
tar xf pip-*.tar.gz
cd pip-*
python setup.py install --prefix=$LOCAL

これでpipのインストールが完了した。

Install Sphinx

続いてpipを使ってSphinxに必要なパッケージをインストールしていく。babelとjinja2だけpytzとMarkUpSafeの依存 関係が必要なので，これらを先にインストールしていく。また，一個ずつpipでインストールするのは煩雑なので，Sphinxだけ最後にインストールする ようにして，for文を使ったシェルスクリプトで一括でインストールする。

cd $LOCAL/src/python
pip install --user pytz-*.tar.*
pip install --user MarkupSafe-*.tar.*

for i in *.tar*
do
 [ "${i%%*Sphinx*}" ] && pip install --user "$i"
done

pip install --user Sphinx-*.tar.*

これでSphinxのインストールは完了した。

Conclusion

Sphinxをソースコードからインストールする方法を記した。必要なものは全てソースからインストールしたのでPythonのバージョンに依存せず，2でも3でも対応できた。実際には，Python2.7と3.3で動作を確認できた。

普段はpipを使っていてあまり意識しないが，Sphinxはたくさんの小さなパッケージに依存していることが分かった。1個ずつ手動でインストールするのは面倒なので，pipが便利だと思った。たぶん今回のようにオフラインの環境にインストールすることはこの先もあまりないと思うので勉強になった。