secretbase.log

.NET/C#/Pythonなど

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: というエラーが出ます。
う~ん。なぜだろうと思い、 @ 先生に聞いてみました。

(.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]: でそのままリターンキーを押した場合