sphinx-build

概要

sphinx-build [オプション] <ソースディレクトリ> <出力ディレクトリ> [ファイル名 …]

説明

sphinx-build は、<ソースディレクトリ> 内のファイルからドキュメントを生成し、<出力ディレクトリ> に配置します。

sphinx-build は、設定のために <ソースディレクトリ>/conf.py を探します。 sphinx-quickstart(1) を使用して、conf.py を含むテンプレートファイルを生成できます。

sphinx-build は、さまざまな形式でドキュメントを作成できます。形式は、コマンドラインでビルダー名を指定することで選択されます。デフォルトは HTML です。ビルダーは、ドキュメント処理に関連する他のタスクを実行することもできます。使用可能なビルダーのリストについては、ビルダー を参照してください。

デフォルトでは、古いものはすべてビルドされます。個々のファイル名を指定することで、選択したファイルの出力のみをビルドできます。

オプション

-M buildername

makeモードを使用して、ビルダーを選択します。 Sphinx のすべての組み込みビルダーのリストについては、ビルダー を参照してください。拡張機能は独自のビルダーを追加できます。

重要

Sphinx は、他のオプションが渡される前に、ソースディレクトリと出力ディレクトリと共に、最初に -M オプションが使用された場合にのみ、それを認識します。例えば

sphinx-build -M html ./source ./build --fail-on-warning

makeモードは、デフォルトの Makefile または Make.bat と同じビルド機能を提供し、以下の追加のビルドパイプラインを提供します。

latexpdf

LaTeX ファイルをビルドし、pdflatex または latex_engine 設定に従って実行します。 language が 'ja' に設定されている場合、自動的に platex/dvipdfmx latex to PDF パイプラインを使用します。

info

Texinfo ファイルをビルドし、makeinfo を実行します。

注意

makeモードを使用する場合のデフォルトの出力ディレクトリの場所は、-b を使用する場合のデフォルトとは異なります。

  • doctree は <出力ディレクトリ>/doctrees に保存されます

  • 出力ファイルは <出力ディレクトリ>/<ビルダー名> に保存されます

バージョン 1.2.1 で追加されました。

-b buildername, --builder buildername

ビルダーを選択します。

Sphinx のすべての組み込みビルダーのリストについては、ビルダー を参照してください。拡張機能は独自のビルダーを追加できます。

バージョン 7.3 で変更: --builder ロングオプションを追加。

-a, --write-all

指定された場合、常にすべての出力ファイルを書き込みます。デフォルトでは、新しいソースファイルと変更されたソースファイルの出力ファイルのみが書き込まれます。（これはすべてのビルダーに適用されるわけではありません。）

注意

このオプションは、ソースファイルを再読み込みしません。すべてのファイルを読み込んで再処理するには、代わりに --fresh-env を使用してください.

バージョン 7.3 で変更: --write-all ロングオプションを追加。

-E, --fresh-env

保存された 環境（すべての相互参照をキャッシュする構造体）を使用せず、完全に再構築します。デフォルトでは、前回の実行以降に新しく作成されたか変更されたソースファイルのみを読み込んで解析します。

バージョン 7.3 で変更: --fresh-env ロングオプションを追加。

-t tag, --tag tag

タグ *tag* を定義します。これは、特定のタグが設定されている場合にのみコンテンツを含める only ディレクティブに関連します。詳細については、タグに基づいたコンテンツのインクルード を参照してください。

バージョン 0.6 で追加されました。

バージョン 7.3 で変更: --tag ロングオプションを追加。

-d path, --doctree-dir path

Sphinx は出力ファイルを書き込む前にすべてのソースファイルを読み込んで解析する必要があるため、解析されたソースファイルは「doctree pickles」としてキャッシュされます。通常、これらのファイルはビルドディレクトリの下の .doctrees というディレクトリに配置されます。このオプションを使用すると、別のキャッシュディレクトリを選択できます（doctree はすべてのビルダー間で共有できます）。

バージョン 7.3 で変更: --doctree-dir ロングオプションを追加。

-j N, --jobs N

マルチプロセッサマシンでのビルドをより効率的にするために、ビルドを *N* プロセスに並列に分散します。この機能は、「fork」をサポートするシステムでのみ機能します。Windows はサポートされていません。Sphinx のすべてのパーツとすべてのビルダーが並列化できるわけではないことに注意してください。 auto 引数が指定された場合、Sphinx は CPU の数を *N* として使用します。デフォルトは 1 です。

バージョン 1.2 で追加: このオプションは *実験的* と見なされるべきです。

バージョン 1.7 で変更: auto 引数をサポート。

バージョン 6.2 で変更: --jobs ロングオプションを追加。

-c path, --config-dir path

ソースディレクトリで conf.py を探さず、代わりに指定された設定ディレクトリを使用します。設定値によって指定された他のさまざまなファイルとパスは、設定ディレクトリからの相対パスであると想定されているため、この場所にも存在する必要があることに注意してください。

バージョン 0.3 で追加されました。

バージョン 7.3 で変更: --config-dir ロングオプションを追加。

-C, --isolated

設定ファイルを探しません。 --define オプションを介してのみオプションを取得します。

バージョン 0.5 で追加されました。

バージョン 7.3 で変更: --isolated ロングオプションを追加。

-D setting=value, --define setting=value

conf.py ファイルで設定されている設定値をオーバーライドします。値は数値、文字列、リスト、または辞書値でなければなりません。

リストの場合、要素をカンマで区切って指定できます。例: -D html_theme_path=path1,path2。

辞書値の場合、設定名とキーを次のように指定します。例: -D latex_elements.docclass=scrartcl。

ブール値の場合、値として 0 または 1 を使用します。

バージョン 0.6 で変更: 値として辞書値が使用できるようになりました。

バージョン 1.3 で変更: 値としてリスト値も使用できるようになりました。

バージョン 7.3 で変更: --define ロングオプションが追加されました。

-A name=value, --html-define name=value

HTML テンプレート内で name に value を割り当てます。

バージョン 0.5 で追加されました。

バージョン 7.3 で変更: --html-define ロングオプションが追加されました。

-n, --nitpicky

nitpicky モードで実行します。現在、これは見つからないすべての参照に対して警告を生成します。一部の参照を「既知の欠落」として除外する方法については、設定値 nitpick_ignore を参照してください。

バージョン 7.3 で変更: --nitpicky ロングオプションが追加されました。

-N, --no-color

カラー出力を行いません。

バージョン 1.6 で変更: --no-color ロングオプションが追加されました。

--color

カラー出力を行います。デフォルトでは自動検出されます。

バージョン 1.6 で追加。

-v, --verbose

冗長性（ログレベル）を上げます。このオプションは最大3回指定でき、より詳細なデバッグログ出力が得られます。 -T を暗黙的に指定します。

バージョン 1.2 で追加。

バージョン 7.3 で変更: --verbose ロングオプションが追加されました。

-q, --quiet

標準出力には何も出力せず、警告とエラーのみを標準エラーに出力します。

バージョン 7.3 で変更: --quiet ロングオプションが追加されました。

-Q, --silent

標準出力には何も出力せず、警告も抑制します。エラーのみが標準エラーに出力されます。

バージョン 7.3 で変更: --silent ロングオプションが追加されました。

-w file, --warning-file file

警告 (およびエラー) を、標準エラーに加えて、指定されたファイルに書き込みます。

バージョン 7.3 で変更: file に書き込む際に、ANSI 制御シーケンスが削除されます。

バージョン 7.3 で変更: --warning-file ロングオプションが追加されました。

-W, --fail-on-warning

警告をエラーに変換します。つまり、ビルド中に警告が発生した場合、sphinx-build は終了ステータス 1 で終了します。

バージョン 7.3 で変更: --fail-on-warning ロングオプションが追加されました。

バージョン 8.1 で変更: sphinx-build は最初の警告で終了するのではなく、ビルド全体を実行し、警告が発生した場合は終了ステータス 1 で終了します。この動作は、以前は --keep-going で有効化されていました。

--keep-going

Sphinx 8.1 以降、--keep-going は常に有効になっています。以前は、--fail-on-warning を使用している場合にのみ適用可能でした。これは、デフォルトでは最初の警告で sphinx-build を終了させていました。--keep-going を使用すると、sphinx-build は最後まで実行され、エラーが発生した場合は終了ステータス 1 で終了します。

バージョン 1.8 で追加。

バージョン 8.1 で変更: sphinx-build は最初の警告で終了しなくなったため、事実上 --fail-on-warning は常に有効になっています。このオプションは互換性のために残されていますが、将来のバージョンで削除される可能性があります。

-T, --show-traceback

処理されない例外が発生した場合に、完全なトレースバックを表示します。指定しない場合、概要のみが表示され、トレースバック情報は詳細な分析のためにファイルに保存されます。

バージョン 1.2 で追加。

バージョン 7.3 で変更: --show-traceback ロングオプションが追加されました。

-P, --pdb

(デバッグにのみ役立ちます。) ビルド中に処理されない例外が発生した場合、Python デバッガー pdb を実行します。

バージョン 7.3 で変更: --pdb ロングオプションが追加されました。

--exception-on-warning

ビルド中に警告が発生した場合に例外を発生させます。これは、--pdb と組み合わせて警告をデバッグするのに役立ちます。

バージョン 8.1 で追加。

-h, --help, --version

使用方法の概要または Sphinx のバージョンを表示します。

バージョン 1.2 で追加。

ソースディレクトリとビルドディレクトリの後に、コマンドラインで1つ以上のファイル名を指定することもできます。Sphinx は、これらの出力ファイル (およびその依存関係) のみをビルドしようとします。

環境変数

sphinx-build は以下の環境変数を参照します

MAKE

make コマンドへのパス。コマンド名も許可されます。sphinx-build はこれを使用して、make モードでサブビルドプロセスを呼び出します。

Makefile オプション

sphinx-quickstart によって作成される Makefile と make.bat ファイルは、通常、-b と -d オプションのみを指定して sphinx-build を実行します。しかし、動作をカスタマイズするために以下の変数をサポートしています。

PAPER

これは、latex_elements の 'papersize' キーを設定します。つまり、PAPER=a4 はそれを 'a4paper' に、PAPER=letter は 'letterpaper' に設定します。

注意

この環境変数の使用は、Sphinx 1.5 で a4 または letter が必要な a4paper または letterpaper の代わりに LaTeX ドキュメントのオプションとして使用されてしまうため、壊れていました。1.7.7 で修正されました。

SPHINXBUILD

sphinx-build の代わりに使用するコマンド。

BUILDDIR

sphinx-quickstart で選択されたものとは異なるビルドディレクトリを使用します。

SPHINXOPTS

sphinx-build の追加オプション。これらのオプションは、ショートカット変数 **O**（大文字の「o」）を介して設定することもできます。

NO_COLOR

設定されている場合（値に関係なく）、sphinx-build は端末出力で色を使用しません。NO_COLOR は FORCE_COLOR よりも優先されます。このコミュニティ標準をサポートする他のライブラリについては、no-color.org を参照してください。

バージョン 4.5.0 で追加されました。

FORCE_COLOR

設定されている場合（値に関係なく）、sphinx-build は端末出力で色を使用します。NO_COLOR は FORCE_COLOR よりも優先されます。

バージョン 4.5.0 で追加されました。

非推奨警告

ユーザーのドキュメントをビルドする際に、RemovedInSphinxXXXWarning のような非推奨警告が表示される場合、一部の Sphinx 拡張機能が非推奨の機能を使用しています。その場合は、拡張機能の作者に報告してください。

非推奨警告を無効にするには、環境変数 PYTHONWARNINGS= を環境に設定してください。例えば

  • PYTHONWARNINGS= make html （Linux/Mac）

  • export PYTHONWARNINGS= を実行してから make html を実行する（Linux/Mac）

  • set PYTHONWARNINGS= を実行してから make html を実行する（Windows）

  • Makefile/make.bat を変更して環境変数を設定する

関連項目

sphinx-quickstart(1)