setuptools連係

Sphinxは、独自コマンドの BuildDoc でsetuptoolsとdistutilsとの連係をサポートしています。

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 で追加.

A boolean that ensures index.html will be linked to the master doc. Default is false.

setup.py に -i フラグを渡す方法でも設定できます:

$ python setup.py build_sphinx -i

バージョン 1.0 で追加.

著作権表示の文字列。デフォルトは '' です。

バージョン 1.3 で追加.

nitpicky

エラーチェックが厳格なモードで実行されます。現在では、すべての見つからない参照に対して警告を生成するような実装になっています。 nitpick_ignore は警告する必要の無いものを除外する設定です。

バージョン 1.8 で追加.

pdb

A boolean to configure pdb on exception. Default is false.

バージョン 1.5 で追加.