virtualenv 環境で sphinx を試してエラーが出て先生に尋ねたら解決した
Python のパッケージをインストールする場合、virtualenv を使うのが常識のよう なので、sphinxやその拡張もシステムに直接インストールせずに、virtualenv環境でやってみようと考えていました。
- sphinxのビルド環境を virtualenv で用意する(ドキュメント毎にsphinxの拡張の導入も楽になることも期待)
- virtualenv 自体も 隠しディレクトリとして sphinx のビルド環境に含めたい
そこで実験をするために、下記手順を行いました。
(環境は、Windows 7です)
適当なディレクトリに移動 ( %HOME%\work\temp とか ) に移動し下記コマンドを実行。
virtualenv .env .env\Scripts\activate.bat pip install sphinx sphinx-quickstart make.bat html
make html でエラーが出る
ERROR: Error in "currentmodule" directive: というエラーが出ます。
う~ん。なぜだろうと思い、 @shimizukawa 先生に聞いてみました。
(.env) C:\Users\tkondou\work\temp>make.bat html Making output directory... Running Sphinx v1.1.3 loading pickled environment... not yet created building [html]: targets for 4 source files that are out of date updating environment: 4 added, 0 changed, 0 removed reading sources... [ 25%] .env/Lib/site-packages/sphinx/ext/autosummary/templat s/autosummary/base reading sources... [ 50%] .env/Lib/site-packages/sphinx/ext/autosummary/templat s/autosummary/class reading sources... [ 75%] .env/Lib/site-packages/sphinx/ext/autosummary/templat s/autosummary/module reading sources... [100%] index C:\Users\tkondou\work\temp\.env\Lib\site-packages\sphinx\ext\autosummary\templa es\autosummary\base.rst:4: ERROR: Error in "currentmodule" directive: maximum 1 argument(s) allowed, 3 supplied. .. currentmodule:: {{ module }} C:\Users\tkondou\work\temp\.env\Lib\site-packages\sphinx\ext\autosummary\templa es\autosummary\class.rst:4: ERROR: Error in "currentmodule" directive: maximum 1 argument(s) allowed, 3 supplied. ...
原因
.env 以下にインストールしたsphinxに含まれている rstファイルもビルド対象になってしまっていることが原因でした。
sphinx の挙動として、ソースディレクトリを分離しない場合は、カレントディレクトリがソースディレクトリに指定されます*1
その場合、 .env もソースフォルダとして指定されてしまい、.envの奥深くに存在する .rstファイルをビルドしようとして、エラーが出るとのことです。
解決策
.env をビルド対象から外します。
conf.py の exclude_patterns に .env を追加します。文字列として追加するので '' で囲んでくださいね。
# List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. exclude_patterns = ['_build', '.env']
今後の予定
virtualenv のフォルダはドキュメントフォルダに含めないほうがいいのかもしれない。それとも、sourceフォルダを分けたほうがいいのか、ベストプラクティスの模索は続きます。
*1:> Separate source and build directories (y/N) [n]: でそのままリターンキーを押した場合