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

On this page

Site navigation

setuptools連係¶

setuptools連係の使用¶

setuptools連係のオプション¶