setuptools連係¶
Sphinxは、独自コマンドの BuildDoc
でsetuptoolsとdistutilsとの連係をサポートしています。
バージョン 5.0 で非推奨: This feature will be removed in v7.0.
setuptools連係の使用¶
Sphinxのビルドはdistutilsから起動でき、Sphinxの設定ファイルの代わりに setup.py
や setup.cfg
にいくつかのSphinxのオプションが設定できます。
例えば、 setup.py
に次のように書けます:
# this is only necessary when not using setuptools/distribute
from sphinx.setup_command import BuildDoc
cmdclass = {'build_sphinx': BuildDoc}
name = 'My project'
version = '1.2'
release = '1.2.0'
setup(
name=name,
author='Bernard Montgomery',
version=release,
cmdclass=cmdclass,
# these are optional and override conf.py settings
command_options={
'build_sphinx': {
'project': ('setup.py', name),
'version': ('setup.py', version),
'release': ('setup.py', release),
'source_dir': ('setup.py', 'doc')}},
)
注釈
Sphinxのオプションを setup()
コマンドに直接設定する場合は、変数名にあるアンダースコアをハイフンに置き換えてください。上の例では source-dir
が source_dir
に変わっています。
また、 setup.cfg
に次のセクションを追加する方法もあります:
[build_sphinx]
project = 'My project'
version = 1.2
release = 1.2.0
source-dir = 'doc'
設定できたら、 setup.py
の適切なコマンドを実行して、連係機能を呼び出してください:
$ python setup.py build_sphinx
setuptools連係のオプション¶
- fresh-env¶
真偽値で、保存されている環境オブジェクトをビルド時に破棄するかどうかを決定します。デフォルトは偽です。
setup.py
に -E フラグを渡す方法でも設定できます:$ python setup.py build_sphinx -E
- all-files¶
真偽値で、全てのファイルを最初からビルドし直すかどうかを決定します。デフォルトは偽です。
setup.py
に -a フラグを渡す方法でも設定できます:$ python setup.py build_sphinx -a
- source-dir¶
対象とするソースディレクトリ。
setup.py
やsetup.cfg
からの相対パスでも、絶対パスでも構いません。デフォルトは、どちらかにconf.py
があれば./doc
あるいは./docs
です。それ以外の場合は、現在のディレクトリです。setup.py
に -s を渡す方法でも設定できます:$ python setup.py build_sphinx -s $SOURCE_DIR
- build-dir¶
ビルド対象のディレクトリ。
setup.py
やsetup.cfg
からの相対パスでも、絶対パスでも構いません。デフォルトは./build/sphinx
です。
- config-dir¶
設定ディレクトリの場所。
setup.py
やsetup.cfg
からの相対パスでも、絶対パスでも構いません。デフォルトでは source-dir を使います。setup.py
に -c フラグを渡す方法でも設定できます:$ python setup.py build_sphinx -c $CONFIG_DIR
バージョン 1.0 で追加.
- builder¶
使用するビルダーかビルダーのリスト。デフォルトは
html
です。setup.py
に -b フラグを渡す方法でも設定できます:$ python setup.py build_sphinx -b $BUILDER
バージョン 1.6 で変更: コンマあるいは空白で区切ったビルダーのリストも使えるようになりました。
- warning-is-error¶
真偽値で、Sphinxの警告が出たらビルドを失敗させます。デフォルトは偽です。
setup.py
に -W フラグを渡す方法でも設定できます:$ python setup.py build_sphinx -W
バージョン 1.5 で追加.
- project¶
ドキュメントを書いているプロジェクト名。デフォルトは
''
です。バージョン 1.0 で追加.
- version¶
短いX.Y形式のバージョン文字列。デフォルトは
''
です。バージョン 1.0 で追加.
- release¶
alpha/beta/rcタグを含む完全なバージョン文字列。デフォルトでは
''
です。バージョン 1.0 で追加.
- today¶
現在の日付をフォーマットする方式の指定。これは
|today|
を置き換える時に使用されます。デフォルトは''
です。バージョン 1.0 で追加.
- link-index¶
A boolean that ensures index.html will be linked to the root doc. Default is false.
setup.py
に -i フラグを渡す方法でも設定できます:$ python setup.py build_sphinx -i
バージョン 1.0 で追加.
- copyright¶
著作権表示の文字列。デフォルトは
''
です。バージョン 1.3 で追加.
- nitpicky¶
エラーチェックが厳格なモードで実行されます。現在では、すべての見つからない参照に対して警告を生成するような実装になっています。
nitpick_ignore
は警告する必要の無いものを除外する設定です。バージョン 1.8 で追加.
- pdb¶
例外に
pdb
を設定するためのブール値です。デフォルトは偽です。バージョン 1.5 で追加.