設定

設定ディレクトリには、conf.py という名前のファイルが含まれている必要があります。このファイル（Python コードを含む）は「ビルド設定ファイル」と呼ばれ、Sphinx の入力および出力動作をカスタマイズするために必要な（ほぼ）すべての設定が含まれています。

オプションのファイル docutils.conf を設定ディレクトリに追加して、Sphinx によって上書きまたは設定されていない場合に Docutils の設定を調整できます。

注意すべき重要な点

  • 特に記載がない限り、値は文字列である必要があり、デフォルトは空の文字列です。

  • 「完全修飾名」（FQN）という用語は、モジュール内のインポート可能な Python オブジェクトの名前を指す文字列を指します。たとえば、完全修飾名 "sphinx.builders.Builder" は、sphinx.builders モジュールの Builder クラスを意味します。

  • ドキュメント名は、パス区切り文字として / を使用し、ファイル名拡張子は含まれません。

  • グロブスタイルのパターンが許可されている場合、標準のシェル構造（*、?、[...]、および [!...]）を使用できます。これらのいずれもスラッシュ（/）に一致しないという機能があります。二重のアスタリスク ** は、スラッシュを含む任意の文字シーケンスに一致するために使用できます。

ヒント

設定ファイルは、ビルド時に Python コードとして実行され（importlib.import_module() を使用し、現在のディレクトリを設定ディレクトリに設定）、したがって、任意の複雑なコードを実行できます。

次に、Sphinx はファイルの名前空間から簡単な名前を読み取り、それを設定として使用します。一般に、設定値は単純な文字列、数値、または単純な値のリストまたは辞書である必要があります。

設定名前空間の内容はピクルされます（Sphinx が設定の変更を検出できるようにするため）。したがって、ピクルできない値を含めることはできません。該当する場合は、del で名前空間から削除してください。モジュールは自動的に削除されるため、インポートされたモジュールを削除する必要はありません。

プロジェクトタグ

設定ファイルで使用可能な tags という名前の特別なオブジェクトがあり、プロジェクトタグを公開します。タグは、--tag コマンドラインオプションまたは tags.add('tag') のいずれかを介して定義されます。ビルダーの名前とフォーマットタグは、conf.py では使用できないことに注意してください。

これは、次のように定義されたタグを照会および変更するために使用できます。

  • タグが設定されているかどうかを照会するには、'tag' in tags を使用します。

  • タグを追加するには、tags.add('tag') を使用します。

  • タグを削除するには、tags.remove('tag') を使用します。

プロジェクト情報

project
型:
str
デフォルト:
'プロジェクト名が設定されていません'

文書化されたプロジェクトの名前。例

project = 'Thermidor'
author
型:
str
デフォルト:
'作成者名が設定されていません'

プロジェクトの作成者。例

author = 'Joe Bloggs'
型:
str | Sequence[str]
デフォルト:
''

著作権表示です。許可される形式は以下の通りです。ここで「YYYY」は4桁の年を表します。

  • copyright = 'YYYY'

  • copyright = 'YYYY, 著者名'

  • copyright = 'YYYY 著者名'

  • copyright = 'YYYY-YYYY, 著者名'

  • copyright = 'YYYY-YYYY 著者名'

バージョン 3.5 で追加: project_copyright エイリアス。

バージョン 7.1 で変更: 値は上記形式の著作権表示のシーケンスでもよく、それぞれが個別の行に表示されるようになりました。

version
型:
str
デフォルト:
''

プロジェクトのメジャーバージョンで、|version| デフォルトの置換の代替として使用されます。

これは version = '4.2' のようなものです。プロジェクトの完全なバージョンは、release で定義されます。

プロジェクトで「完全」バージョンと「メジャー」バージョンを区別する意味がない場合は、version と release の両方に同じ値を設定してください。

release
型:
str
デフォルト:
''

プロジェクトの完全なバージョンで、|release| デフォルトの置換、および例えば HTML テンプレートなどで使用されます。

これは release = '4.2.1b0' のようなものです。メジャー（短い）プロジェクトバージョンは、version で定義されます。

プロジェクトで「完全」バージョンと「メジャー」バージョンを区別する意味がない場合は、version と release の両方に同じ値を設定してください。

一般設定

needs_sphinx
型:
str
デフォルト:
''

プロジェクトをビルドするために必要な Sphinx の最小サポートバージョンを設定します。形式は、'1.1' のような 'major.minor' バージョン文字列にする必要があります。Sphinx はそのバージョンと比較し、実行中の Sphinx のバージョンが古すぎる場合はプロジェクトのビルドを拒否します。デフォルトでは、最小バージョンはありません。

バージョン 1.0 で追加。

バージョン 1.4 で変更: 'major.minor.micro' バージョン文字列を許可します。

extensions
型:
list[str]
デフォルト:
[]

Sphinx 拡張機能のモジュール名である文字列のリスト。これらは、Sphinx にバンドルされている拡張機能（sphinx.ext.* という名前）でも、カスタムのファーストパーティまたはサードパーティの拡張機能でも構いません。

サードパーティの拡張機能を使用するには、それがインストールされていることを確認し、次のように extensions リストに含める必要があります。

extensions = [
    ...
    'numpydoc',
]

ファーストパーティの拡張機能には2つのオプションがあります。構成ファイル自体を拡張機能にできます。そのためには、setup() 関数を構成ファイルに指定するだけで済みます。それ以外の場合は、カスタム拡張機能をインポート可能にし、Python パスにあるディレクトリに配置する必要があります。

sys.path を変更する場合は、絶対パスが使用されていることを確認してください。カスタム拡張機能が 構成ディレクトリ を基準とするディレクトリにある場合は、次のように os.path.abspath() を使用してください。

import os, sys; sys.path.append(os.path.abspath('sphinxext'))

extensions = [
   ...
   'extname',
]

上記で説明したディレクトリ構造は次のようになります。

<project directory>/
├── conf.py
└── sphinxext/
    └── extname.py
needs_extensions
型:
dict[str, str]
デフォルト:
{}

設定されている場合、この値は extensions の拡張機能のバージョン要件を指定する辞書である必要があります。バージョン文字列は、'major.minor' 形式にする必要があります。要件はすべての拡張機能に対して指定する必要はなく、チェックしたい拡張機能に対してのみ指定します。例:

needs_extensions = {
    'sphinxcontrib.something': '1.5',
}

これには、拡張機能が setup() 関数でバージョンを宣言する必要があります。詳細については、Sphinx API を参照してください。

バージョン 1.3 で追加。

manpages_url
型:
str
デフォルト:
''

manpage ロールを相互参照するための URL。これが https://manpages.debian.org/{path} に定義されている場合、:manpage:`man(1)` ロールは <https://manpages.debian.org/man(1)> にリンクされます。利用可能なパターンは次のとおりです。

page

マニュアルページ（man）

section

マニュアルセクション（1）

path

指定された元のマニュアルページとセクション（man(1)）

これは man.1 として指定されたマニュアルページもサポートします。

# To use manpages.debian.org:
manpages_url = 'https://manpages.debian.org/{path}'
# To use man7.org:
manpages_url = 'https://man7.org/linux/man-pages/man{section}/{page}.{section}.html'
# To use linux.die.net:
manpages_url = 'https://linux.die.net/man/{section}/{page}'
# To use helpmanual.io:
manpages_url = 'https://helpmanual.io/man{section}/{page}'

バージョン 1.7 で追加。

today
today_fmt

これらの値は、|today| デフォルトの置換の代替として使用される、現在の日付のフォーマット方法を決定します。

  • today を空でない値に設定すると、それが使用されます。

  • それ以外の場合は、現在の時刻が time.strftime() と today_fmt で指定された形式を使用してフォーマットされます。

today のデフォルトは '' であり、today_fmt のデフォルトは '%b %d, %Y' です（または、language で翻訳が有効になっている場合は、選択したロケールの同等の形式）。

図の番号付けのオプション

numfig
型:
bool
デフォルト:
False

True の場合、図、表、コードブロックにはキャプションがある場合に自動的に番号が付けられます。numref ロールが有効になります。今のところ、HTML および LaTeX ビルダーでのみ遵守されます。

注釈

LaTeX ビルダーは、このオプションが有効かどうかに関係なく、常に番号を割り当てます。

バージョン 1.3 で追加。

numfig_format
型:
dict[str, str]
デフォルト:
{}

'figure'、'table'、'code-block' および 'section' を図番号の形式に使用される文字列にマッピングする辞書。マーカー %s は図番号に置き換えられます。

デフォルトは次のとおりです。

numfig_format = {
    'code-block': 'Listing %s',
    'figure': 'Fig. %s',
    'section': 'Section',
    'table': 'Table %s',
}

バージョン 1.3 で追加。

numfig_secnum_depth
型:
int
デフォルト:
1

  • 0 に設定すると、図、表、コードブロックは 1 から始まる連番になります。

  • 1 の場合、番号付けは x.1, x.2, … となり、x はセクション番号を表します。（トップレベルのセクションがない場合、プレフィックスは追加されません。）これは、toctree ディレクティブの :numbered: オプションでセクション番号付けが有効になっている場合にのみ適用されます。

  • 2 の場合、番号付けは x.y.1, x.y.2, … となり、x はセクション番号を、y はサブセクション番号を表します。セクションの直下にある場合は y. プレフィックスは付かず、トップレベルのセクションがない場合はプレフィックスは追加されません。

  • 上記の規則に従って、他の任意の正の整数を使用できます。

バージョン 1.3 で追加。

バージョン 1.7 で変更: numfig が True に設定されている場合、LaTeX ビルダーはこの設定に従います。

ハイライトのオプション

highlight_language
型:
str
デフォルト:
'default'

ソースコードをハイライトするデフォルトの言語。デフォルトは 'default' で、Pythonコードとしてのハイライトに失敗した場合に警告を抑制します。

値は有効な Pygments レクサー名である必要があります。詳細については、コード例の表示を参照してください。

バージョン 0.5 で追加。

バージョン 1.4 で変更: デフォルトは 'default' になりました。

highlight_options
型:
dict[str, dict[str, Any]]
デフォルト:
{}

Pygments レクサー名をそれらのオプションにマッピングする辞書。これらはレクサー固有です。各レクサーが理解するオプションについては、Pygments のドキュメントを参照してください。

例

highlight_options = {
  'default': {'stripall': True},
  'php': {'startinline': True},
}

バージョン 1.3 で追加。

バージョン 3.5 で変更: 複数のレクサーのハイライトオプションの設定を許可します。

pygments_style
型:
str
デフォルト:
'sphinx'

ソースコードの Pygments ハイライトに使用するスタイル名。設定されていない場合、HTML 出力にはテーマのデフォルトスタイルまたは 'sphinx' が選択されます。

バージョン 0.3 で変更: 値がカスタム Pygments スタイルクラスの完全修飾名である場合、これがカスタムスタイルとして使用されます。

HTTPリクエストのオプション

tls_verify
型:
bool
デフォルト:
True

Trueの場合、Sphinxはサーバー証明書を検証します。

バージョン 1.5 で追加。

tls_cacerts
型:
str | dict[str, str]
デフォルト:
''

CAの認証ファイルへのパス、または証明書が含まれるディレクトリへのパス。これにより、ホスト名を証明書ファイルのパスにマッピングする辞書も許可されます。証明書は、サーバー証明書を検証するために使用されます。

バージョン 1.5 で追加。

ヒント

Sphinxは、内部でHTTPライブラリとして requests を使用します。tls_cacerts が設定されていない場合、Sphinxはrequestsのデフォルトの動作に戻ります。詳細については、SSL証明書の検証を参照してください。

user_agent
型:
str
デフォルト:
'Mozilla/5.0 (X11; Linux x86_64; rv:100.0) Gecko/20100101 Firefox/100.0 Sphinx/X.Y.Z'

SphinxがHTTPリクエストに使用するUser-Agentを設定します。

バージョン 2.3 で追加。

国際化のオプション

これらのオプションは、Sphinxの*ネイティブ言語サポート*に影響を与えます。詳細については、国際化のドキュメントを参照してください。

language
型:
str
デフォルト:
'en'

ドキュメントが記述されている言語のコード。Sphinxによって自動的に生成されるテキストは、その言語になります。また、Sphinxは、locale_dirs から取得した翻訳セットを使用して、ドキュメントの個々の段落を置換しようとします。Sphinxは、figure_language_filename によって名前が付けられた言語固有の図（たとえば、myfigure.png のドイツ語版は、デフォルト設定では myfigure.de.png になります）を検索し、元の図の代わりにそれらを代用します。LaTeXビルダーでは、*Babel*パッケージのオプションとして適切な言語が選択されます。

バージョン 0.5 で追加。

バージョン 1.4 で変更: 図の置換をサポート

バージョン 5.0 で変更: デフォルトは 'en' になりました（以前は None だった）。

Sphinxで現在サポートされている言語は次のとおりです。

  • ar – アラビア語

  • bg – ブルガリア語

  • bn – ベンガル語

  • ca – カタルーニャ語

  • cak – カクチケル語

  • cs – チェコ語

  • cy – ウェールズ語

  • da – デンマーク語

  • de – ドイツ語

  • el – ギリシャ語

  • en – 英語（デフォルト）

  • eo – エスペラント

  • es – スペイン語

  • et – エストニア語

  • eu – バスク語

  • fa – イラン語

  • fi – フィンランド語

  • fr – フランス語

  • he – ヘブライ語

  • hi – ヒンディー語

  • hi_IN – ヒンディー語（インド）

  • hr – クロアチア語

  • hu – ハンガリー語

  • id – インドネシア語

  • it – イタリア語

  • ja – 日本語

  • ko – 韓国語

  • lt – リトアニア語

  • lv – ラトビア語

  • mk – マケドニア語

  • nb_NO – ノルウェー語ブークモール

  • ne – ネパール語

  • nl – オランダ語

  • pl – ポーランド語

  • pt – ポルトガル語

  • pt_BR – ブラジルポルトガル語

  • pt_PT – ヨーロッパポルトガル語

  • ro – ルーマニア語

  • ru – ロシア語

  • si – シンハラ語

  • sk – スロバキア語

  • sl – スロベニア語

  • sq – アルバニア語

  • sr – セルビア語

  • sr@latin – セルビア語（ラテン文字）

  • sr_RS – セルビア語 (キリル文字)

  • sv – スウェーデン語

  • ta – タミル語

  • te – テルグ語

  • tr – トルコ語

  • uk_UA – ウクライナ語

  • ur – ウルドゥー語

  • vi – ベトナム語

  • zh_CN – 中国語 (簡体字)

  • zh_TW – 中国語 (繁体字)

locale_dirs
型:
list[str]
デフォルト:
['locale']

追加のメッセージカタログ ( language 参照) を検索するディレクトリ。ソースディレクトリからの相対パスで指定します。このパスにあるディレクトリは、gettext モジュールによって検索されます。

内部メッセージは sphinx のテキストドメインから取得されます。したがって、この設定に ./locale ディレクトリを追加した場合、メッセージカタログ ( msgfmt を使用して .po 形式からコンパイルされたもの) は ./locale/language/LC_MESSAGES/sphinx.mo に配置する必要があります。個々のドキュメントのテキストドメインは、gettext_compact に依存します。

注釈

sphinx-build の -v オプション は、locale_dirs 設定が期待どおりに機能しているかを確認するのに役立ちます。メッセージカタログディレクトリが見つからない場合は、デバッグメッセージが出力されます。

バージョン 0.5 で追加。

バージョン 1.5 で変更: デフォルト値として locales ディレクトリを使用

gettext_allow_fuzzy_translations
型:
bool
デフォルト:
False

True の場合、メッセージカタログ内の「ファジー」メッセージが翻訳に使用されます。

バージョン 4.3 で追加。

gettext_compact
型:
bool | str
デフォルト:
True

  • True の場合、ドキュメントのテキストドメインは、最上位のプロジェクトファイルの場合はドキュメント名、それ以外の場合はそのベースディレクトリになります。

  • False の場合、ドキュメントのテキストドメインは、ドキュメント名全体になります。

  • 文字列に設定した場合、すべてのドキュメントのテキストドメインはこの文字列に設定され、すべてのドキュメントが単一のテキストドメインを使用するようになります。

gettext_compact = True の場合、ドキュメント markup/code.rst は markup テキストドメインになります。このオプションを False に設定した場合、markup/code になります。このオプションを 'sample' に設定した場合、sample になります。

バージョン 1.1 で追加。

バージョン 3.3 で変更: 文字列値を許可。

gettext_uuid
型:
bool
デフォルト:
False

True の場合、Sphinx はメッセージカタログ内のバージョン追跡のための UUID 情報を生成します。これは、以下の目的で使用されます。

  • .pot ファイル内の各 msgid に UUID 行を追加します。

  • 新しい msgid と以前に保存された古い msgid との類似性を計算します (この計算には時間がかかる場合があります)。

ヒント

計算を高速化したい場合は、サードパーティパッケージ (Levenshtein) を使用できます。その場合は、pip install levenshtein を実行してください。

バージョン 1.3 で追加。

gettext_location
型:
bool
デフォルト:
True

True の場合、Sphinx はメッセージカタログ内のメッセージの場所情報を生成します。

バージョン 1.3 で追加。

gettext_auto_build
型:
bool
デフォルト:
True

True の場合、Sphinx は各翻訳カタログファイルに対して .mo ファイルをビルドします。

バージョン 1.3 で追加。

gettext_additional_targets
型:
set[str] | Sequence[str]
デフォルト:
[]

特定の要素タイプに対して gettext 翻訳を有効にします。例

gettext_additional_targets = {'literal-block', 'image'}

次の要素タイプがサポートされています

  • 'index' – インデックス用語

  • 'literal-block' – リテラルブロック ( :: アノテーションおよび code-block ディレクティブ)

  • 'doctest-block' – doctest ブロック

  • 'raw' – raw コンテンツ

  • 'image' – 画像/図の URI

バージョン 1.3 で追加。

バージョン 4.0 で変更: 画像の代替テキストがデフォルトで翻訳されるようになりました。

バージョン 7.4 で変更: set 型を許可し、推奨するようにしました。

figure_language_filename
型:
str
デフォルト:
'{root}.{language}{ext}'

言語固有の図のファイル名形式。使用可能なフォーマットトークンは次のとおりです。

  • {root}: ファイル名。ファイル拡張子なしで、パスコンポーネントを含みます。例: images/filename。

  • {path}: ファイル名のディレクトリパスコンポーネント。空でない場合は、末尾にスラッシュが付きます。例: images/。

  • {basename}: ディレクトリパスまたはファイル拡張子コンポーネントを含まないファイル名。例: filename。

  • {ext}: ファイル拡張子。例: .png。

  • {language}: 翻訳言語。例: en。

  • {docpath}: 現在のドキュメントのディレクトリパスコンポーネント。空でない場合は、末尾にスラッシュが付きます。例: dirname/。

デフォルトでは、画像ディレクティブ .. image:: images/filename.png は、images/filename.png の画像を使用しており、言語固有の図ファイル名 images/filename.en.png を使用します。

figure_language_filename が以下のように設定されている場合、言語固有の図ファイル名は images/en/filename.png になります。

figure_language_filename = '{path}{language}/{basename}{ext}'

バージョン 1.4 で追加。

バージョン 1.5 で変更: {path} および {basename} トークンを追加しました。

バージョン 3.2 で変更: {docpath} トークンを追加しました。

translation_progress_classes
型:
bool | 'translated' | 'untranslated'
デフォルト:
False

翻訳の進捗状況を示すためにどのクラスを追加するか (ある場合) を制御します。この設定は、翻訳済みおよび未翻訳のコンテンツをすばやく示すために、ドキュメントの翻訳者のみが使用する可能性があります。

True

翻訳可能なコンテンツを持つすべてのノードに、translated クラスと untranslated クラスを追加します。

'translated'

translated クラスのみを追加します。

'untranslated'

untranslated クラスのみを追加します。

False

翻訳の進捗状況を示すクラスを追加しません。

バージョン 7.1 で追加。

マークアップのオプション

default_role
型:
str
デフォルト:
None

デフォルトのロールとして使用する reStructuredText ロール (組み込みまたは Sphinx 拡張機能) の名前。つまり、`このように` マークアップされたテキストに使用されます。これを 'py:obj' に設定すると、`filter` が Python 関数「filter」へのクロスリファレンスになります。

デフォルトのロールは、標準の reStructuredText default-role ディレクティブを使用して、個々のドキュメント内で常に設定できます。

バージョン 0.4 で追加。

keep_warnings
型:
bool
デフォルト:
False

レンダリングされたドキュメントに、警告を「システムメッセージ」段落として保持します。この設定に関係なく、sphinx-build の実行時に、警告は常に標準エラーストリームに書き込まれます。

バージョン 0.5 で追加。

option_emphasise_placeholders
型:
bool
デフォルト:
False

有効にすると、option ディレクティブ内のプレースホルダーが強調表示されます。リテラルの波括弧を表示するには、バックスラッシュでエスケープします(\{)。例えば、option_emphasise_placeholders=True と .. option:: -foption={TYPE} の場合、TYPE が強調表示されてレンダリングされます。

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

primary_domain
型:
str
デフォルト:
'py'

デフォルトの ドメイン の名前。デフォルトドメインを無効にするには None も指定できます。デフォルトは、Pythonドメインを表す 'py' です。

他のドメインにあるオブジェクト (ドメイン名が明示的に指定されているか、default-domain ディレクティブによって選択されているかに関わらず) は、名前が付けられる際にドメイン名が明示的に付加されます (例えば、デフォルトのドメインがCの場合、Python関数は単に「関数」ではなく「Python関数」という名前になります)。例：

primary_domain = 'cpp'

バージョン 1.0 で追加。

rst_epilog
型:
str
デフォルト:
''

読み込まれるすべてのソースファイルの末尾に含められる reStructuredText の文字列。これは、すべてのファイルで利用可能にする必要のある置換を追加できる場所です（他に rst_prolog があります）。例：

rst_epilog = """
.. |psf| replace:: Python Software Foundation
"""

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

rst_prolog
型:
str
デフォルト:
''

読み込まれるすべてのソースファイルの先頭に含められる reStructuredText の文字列。これは、すべてのファイルで利用可能にする必要のある置換を追加できる場所です（他に rst_epilog があります）。例：

rst_prolog = """
.. |psf| replace:: Python Software Foundation
"""

バージョン 1.0 で追加。

show_authors
型:
bool
デフォルト:
False

codeauthor および sectionauthor ディレクティブがビルドされたファイルに出力するかどうかを決定するブール値。

trim_footnote_reference_space
型:
bool
デフォルト:
False

脚注を認識するために reStructuredText パーサーに必要な、出力ではあまり見栄えの良くない脚注参照の前にある空白を削除します。

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

数式に関するオプション

これらのオプションは、数式のマークアップと表記を制御します。

math_eqref_format
型:
str
デフォルト:
'({number})'

数式への参照のラベルを整形するために使用される文字列。{number} プレースホルダーは、数式番号を表します。

例：'Eq.{number}' は、例えば Eq.10 としてレンダリングされます。

バージョン 1.7 で追加。

math_number_all
型:
bool
デフォルト:
False

すべての表示される数式に番号を強制的に付けます。例：

math_number_all = True

バージョン 1.4 で追加。

math_numfig
型:
bool
デフォルト:
True

True の場合、numfig が有効になっているとき、表示される数式はページ間で番号が付けられます。numfig_secnum_depth 設定が適用されます。数式番号を参照するには、numref ロールではなく、eq ロールを使用する必要があります。

バージョン 1.7 で追加。

math_numsep
型:
str
デフォルト:
'.'

numfig が有効で、numfig_secnum_depth が正の値の場合、セクション番号と数式番号の間の区切り文字を定義する文字列。

例：'-' は、1.2-3 としてレンダリングされます。

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

厳密なモードのオプション

nitpicky
型:
bool
デフォルト:
False

True の場合、厳密なモードを有効にします。厳密なモードでは、Sphinx はターゲットが見つからないすべての参照について警告します。これは、すべての参照が有効なターゲットを指していることを保証するため、新しいプロジェクトに推奨されます。

--nitpicky コマンドラインオプションを使用することで、このモードを一時的に有効にできます。「既知の欠落」として欠落した参照をマークする方法については、nitpick_ignore を参照してください。

nitpicky = True

バージョン 1.0 で追加。

nitpick_ignore
型:
set[tuple[str, str]] | Sequence[tuple[str, str]]
デフォルト:
()

"厳密なモード" で警告を生成する際に無視する必要のある (warning_type, target) タプルのセットまたはリスト。 warning_type には、存在する場合はドメイン名を含める必要があることに注意してください。例：

nitpick_ignore = {
    ('py:func', 'int'),
    ('envvar', 'LD_LIBRARY_PATH'),
}

バージョン 1.1 で追加。

バージョン 6.2 で変更: 許容されるコンテナタイプをセット、リスト、またはタプルに変更しました。

nitpick_ignore_regex
型:
set[tuple[str, str]] | Sequence[tuple[str, str]]
デフォルト:
()

nitpick_ignore の拡張バージョンであり、代わりに warning_type および target 文字列を正規表現として解釈します。正規表現は、文字列全体に一致する必要があることに注意してください ( ^ および $ マーカーが挿入された場合と同様)。

例えば、(r'py:.*', r'foo.*bar\.B.*') は、'foo' で始まり、'bar.B' を含むすべての Python エンティティの厳密な警告を無視します。例えば、('py:const', 'foo_package.bar.BAZ_VALUE') や ('py:class', 'food.bar.Barman') などです。

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

バージョン 6.2 で変更: 許容されるコンテナタイプをセット、リスト、またはタプルに変更しました。

オブジェクトシグネチャのオプション

add_function_parentheses
型:
bool
デフォルト:
True

名前が呼び出し可能であることを示すために、関数およびメソッドのロールテキスト (例えば、:func:`input` の内容) に括弧を付加するかどうかを決定するブール値。

maximum_signature_line_length
型:
int | None
デフォルト:
None

シグネチャの文字数が設定された数を超えると、シグネチャ内の各パラメータが個別の論理行に表示されます。

None の場合、最大長はなく、シグネチャ全体が単一の論理行に表示されます。

「論理行」はハードラインブレイクに似ています。ビルダまたはテーマは、単一の論理行を「ソフトラップ」するように選択できます。この設定は、その動作に影響を与えません。

ドメインは、C、C++、Pythonドメインに見られるように、個々のオブジェクトディレクティブでのハードラッピングを抑制するオプションを提供できます（例：py:function:single-line-parameter-list）。

バージョン 7.1 で追加。

strip_signature_backslash
型:
bool
デフォルト:
False

バックスラッシュの削除が有効になっている場合、ドメインディレクティブ内のすべての\\の出現箇所は、文字列リテラル内であっても\に変更されます。これはバージョン3.0以前の動作であり、この変数をTrueに設定すると、その動作が復元されます。

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

toc_object_entries
型:
bool
デフォルト:
True

ドメインオブジェクト（関数、クラス、属性など）の目次エントリを作成します。

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

toc_object_entries_show_parents
型:
'domain' | 'hide' | 'all'
デフォルト:
'domain'

ドメインオブジェクト（関数、クラス、属性など）が目次エントリにどのように表示されるかを決定する文字列。

表示する親の適切な数をドメインが決定できるようにするには、'domain'を使用します。たとえば、PythonドメインはClass.method()とfunction()を表示し、module.レベルの親は除外します。

親をまったく表示せずに要素の名前のみを表示するには、'hide'を使用します（つまり、method()）。

オブジェクトの完全修飾名（つまり、module.Class.method()）を表示し、すべての親を表示するには、'all'を使用します。

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

ソースファイルのオプション

exclude_patterns
型:
Sequence[str]
デフォルト:
()

ソースファイルを検索する際に除外する必要があるglobスタイルのパターンのリスト。これらは、すべてのプラットフォームでディレクトリ区切り文字としてスラッシュを使用して、ソースディレクトリからの相対的なソースファイル名と照合されます。exclude_patternsは、include_patternsよりも優先されます。

パターン例

  • 'library/xml.rst' – library/xml.rstファイルを無視します

  • 'library/xml' – library/xmlディレクトリを無視します

  • 'library/xml*' – library/xmlで始まるすべてのファイルとディレクトリを無視します

  • '**/.git' – すべての.gitディレクトリを無視します

  • 'Thumbs.db' – すべてのThumbs.dbファイルを無視します

exclude_patternsは、html_static_pathとhtml_extra_pathで静的ファイルを検索する場合にも参照されます。

バージョン 1.0 で追加。

include_patterns
型:
Sequence[str]
デフォルト:
('**',)

ソースファイルを検索するために使用されるglobスタイルのパターンのリスト。これらは、すべてのプラットフォームでディレクトリ区切り文字としてスラッシュを使用して、ソースディレクトリからの相対的なソースファイル名と照合されます。デフォルトでは、すべてのファイルがソースディレクトリから再帰的に含まれます。exclude_patternsは、include_patternsよりも優先されます。

パターン例

  • '**' – ソースディレクトリとサブディレクトリ内のすべてのファイル（再帰的）

  • 'library/xml' – library/xmlディレクトリのみ

  • 'library/xml*' – library/xmlで始まるすべてのファイルとディレクトリ

  • '**/doc' – すべてのdocディレクトリ（ドキュメントがソースファイルと同じ場所にある場合に役立つ可能性があります）

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

master_doc
root_doc
型:
str
デフォルト:
'index'

Sphinxは、ソースファイルに含まれるtoctreeディレクティブに基づいてドキュメントのツリーを構築します。これは、マスターのtoctreeディレクティブを含むドキュメントの名前、したがってツリー全体のルートを設定します。例

master_doc = 'contents'

バージョン 2.0 で変更: デフォルトは'index'です（以前は'contents'でした）。

バージョン 4.0 で追加: root_docエイリアス。

source_encoding
型:
str
デフォルト:
'utf-8-sig'

すべてのソースファイルのファイルエンコーディング。推奨されるエンコーディングは'utf-8-sig'です。

バージョン 0.5 で追加。

source_suffix
型:
dict[str, str] | Sequence[str] | str
デフォルト:
{'.rst': 'restructuredtext'}

ソースファイルのファイル拡張子（サフィックス）をファイルタイプにマッピングする辞書。Sphinxは、source_suffixに含まれるサフィックスを持つすべてのファイルをソースファイルと見なします。例

source_suffix = {
    '.rst': 'restructuredtext',
    '.txt': 'restructuredtext',
    '.md': 'markdown',
}

デフォルトでは、Sphinxは'restructuredtext'ファイルタイプのみをサポートしています。他のファイルタイプは、MyST-Parserなどの異なるソースファイルパーサーを登録する拡張機能を追加することで追加できます。サポートされているファイルタイプについては、拡張機能のドキュメントを参照してください。

値が文字列または文字列のシーケンスの場合、Sphinxはそれらがすべて'restructuredtext'ファイルであると見なします。

注釈

ファイル拡張子はドット（'.'）で始まる必要があります。

バージョン 1.3 で変更: ファイル拡張子のリストをサポート。

バージョン 1.8 で変更: ファイル拡張子からファイルタイプへのマップに変更。

スマートクォートのオプション

smartquotes
型:
bool
デフォルト:
True

Trueの場合、スマートクォート変換が使用され、引用符とダッシュを活版印刷的に正しいエンティティに変換します。

バージョン 1.6.6 で追加: 現在削除されているhtml_use_smartypantsを置き換えます。デフォルトでは、manとtextを除くすべてのビルダーに適用されます（smartquotes_excludesを参照）。

注釈

構成ディレクトリにあるdocutils.confファイル（またはグローバルな~/.docutilsファイル）は、対応するDocutilsオプションを使用してスマートクォートを無効化した場合、無条件に尊重されます。ただし、それらを有効化する場合、smartquotesが優先されます。

smartquotes_action
型:
str
デフォルト:
'qDe'

スマートクォート変換をカスタマイズします。許可されているコードについては、以下を参照してください。デフォルトの'qDe'は、通常のq引用符"、'、em-およびen-Dダッシュ---、--、およびe省略記号...を教育します。

'q'

引用符を変換します

'b'

バッククォート引用符を変換します（``double''のみ）

'B'

バッククォート引用符を変換します（``double''と`single'）

'd'

ダッシュを変換します（--をemダッシュに、---をenダッシュに変換します）

'D'

ダッシュの変換（旧式）（-- を en ダッシュに、--- を em ダッシュに変換）

'i'

ダッシュの変換（反転した旧式）（-- を em ダッシュに、--- を en ダッシュに変換）

'e'

省略記号 ... の変換

'w'

'&quot;' エンティティを '"' に変換

バージョン 1.6.6 で追加。

smartquotes_excludes
型:
dict[str, list[str]]
デフォルト:
{'languages': ['ja'], 'builders': ['man', 'text']}

スマートクォート変換を無効にするタイミングを制御します。許可されているキーは 'builders' と 'languages' で、値は文字列のリストです。

各エントリは、smartquotes 設定を無視してスマートクォート変換を無効にするための十分な条件を示します。例:

smartquotes_excludes = {
    'languages': ['ja'],
    'builders': ['man', 'text'],
}

注釈

現在、複数のターゲットを指定して make を呼び出した場合、最初のターゲット名のみが 'builders' エントリに対してテストされ、すべてに対して決定されます。また、make html に続く make text は、make text SPHINXOPTS="-E" の形式で発行して、ソースファイルの再解析を強制する必要があります。これは、キャッシュされたものがすでに変換されているためです。一方、sphinx-build の直接使用では、（デフォルトの使用法では）解析済みのソースファイルをビルダーごとの場所にキャッシュするため、問題は発生しません。

ヒント

特定のビルダー（例: latex）のスマートクォートを効果的に無効化（またはカスタマイズ）する別の方法は、次のように make を使用することです。

make latex SPHINXOPTS="-D smartquotes_action="

これは、前のメモの状況とは対照的に、問題なく make html に続くことができます。

バージョン 1.6.6 で追加。

テンプレートのオプション

template_bridge
型:
str
デフォルト:
''

TemplateBridge のインスタンスを返す callable （または単にクラス）の完全修飾名を持つ文字列。このインスタンスは、HTMLドキュメント、および場合によっては他のビルダー（現在は changes ビルダー）の出力をレンダリングするために使用されます。（HTMLテーマを使用する場合は、テンプレートブリッジをテーマ対応にする必要があることに注意してください。）例:

template_bridge = 'module.CustomTemplateBridge'
templates_path
型:
Sequence[str]
デフォルト:
()

追加のテンプレート（または組み込み/テーマ固有のテンプレートを上書きするテンプレート）を含むパスのリスト。構成ディレクトリからの相対パスとして解釈されます。例:

templates_path = ['.templates']

バージョン 1.3 で変更: これらのファイルはビルドされることを意図していないため、ソースファイルの検出時に自動的に除外されます。

警告制御のオプション

show_warning_types
型:
bool
デフォルト:
True

各警告のタイプを警告メッセージの接尾辞として追加します。たとえば、WARNING: [...] [index] や WARNING: [...] [toc.circular] のようになります。この設定は、suppress_warnings リストに含める警告の種類を決定するのに役立ちます。

バージョン 7.3.0 で追加。

バージョン 8.0.0 で変更: デフォルトが True になりました。

suppress_warnings
型:
Sequence[str]
デフォルト:
()

任意の警告メッセージを抑制するための警告コードのリスト。

デフォルトでは、Sphinx は次の警告コードをサポートしています。

  • app.add_node

  • app.add_directive

  • app.add_role

  • app.add_generic_role

  • app.add_source_parser

  • config.cache

  • docutils

  • download.not_readable

  • epub.unknown_project_files

  • epub.duplicated_toc_entry

  • i18n.inconsistent_references

  • index

  • image.not_readable

  • ref.term

  • ref.ref

  • ref.numref

  • ref.keyword

  • ref.option

  • ref.citation

  • ref.footnote

  • ref.doc

  • ref.python

  • misc.copy_overwrite

  • misc.highlighting_failure

  • toc.circular

  • toc.excluded

  • toc.no_title

  • toc.not_readable

  • toc.secnum

拡張機能も独自の警告タイプを定義できます。ファーストパーティの sphinx.ext 拡張機能によって定義されたものは次のとおりです。

  • autodoc

  • autodoc.import_object

  • autosectionlabel.<document name>

  • autosummary

  • autosummary.import_cycle

  • intersphinx.external

これらのタイプから選択できます。また、最初のコンポーネントのみを指定して、それに関連付けられたすべての警告を除外することもできます。

バージョン 1.4 で追加。

バージョン 1.5 で変更: misc.highlighting_failure を追加

バージョン 1.5.1 で変更: epub.unknown_project_files を追加

バージョン 1.6 で変更: ref.footnote を追加

バージョン 2.1 で変更: autosectionlabel.<document name> を追加

バージョン 3.3.0 で変更: epub.duplicated_toc_entry を追加

バージョン 4.3 で変更: toc.excluded および toc.not_readable を追加

バージョン 4.5 で追加: i18n.inconsistent_references を追加

バージョン 7.1 で追加: index を追加

バージョン 7.3 で追加: config.cache を追加

バージョン 7.3 で追加: toc.no_title を追加

バージョン 8.0 で追加: misc.copy_overwrite を追加

ビルダーオプション

HTML 出力のオプション

これらのオプションは HTML 出力に影響を与えます。さまざまな他のビルダーは HTML 出力から派生しており、これらのオプションも利用します。

html_theme
型:
str
デフォルト:
'alabaster'

HTML 出力のテーマ。HTML テーマセクションを参照してください。

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

バージョン 1.3 で変更: デフォルトのテーマが 'alabaster' になりました。

html_theme_options
型:
dict[str, Any]
デフォルト:
{}

選択したテーマのデザインに影響を与えるオプションの辞書。これらはテーマ固有です。組み込みテーマで理解されるオプションについては、こちらで説明しています。

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

html_theme_path
型:
list[str]
デフォルト:
[]

カスタムテーマをサブディレクトリまたは zip ファイルとして含むパスのリスト。構成ディレクトリからの相対パスとして解釈されます。

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

html_style
型:
Sequence[str] | str
デフォルト:
()

HTML ページに使用するスタイルシート。選択されたテーマで指定されたスタイルシートがデフォルトで使用されます。その名前のファイルが、Sphinx の static/ パス、または html_static_path で指定されたカスタムパスのいずれかに存在する必要があります。テーマのスタイルシートからいくつか追加または上書きするだけの場合は、CSS の @import を使用してテーマのスタイルシートをインポートしてください。

バージョン 5.1 で変更: 値は文字列のイテラブルにできます。

html_title
型:
str
デフォルト:
'プロジェクト リリース ドキュメント'

Sphinx 独自のテンプレートで生成された HTML ドキュメントの「タイトル」。これは、個々のページの <title> タグに追加され、ナビゲーションバーの「最上位」要素として使用されます。

html_short_title
型:
str
デフォルト:
html_title の値

HTML ドキュメントのより短い「タイトル」。これは、ヘッダーと HTML ヘルプドキュメントのリンクに使用されます。

バージョン 0.4 で追加。

html_baseurl
型:
str
デフォルト:
''

HTML ドキュメントのルートを指すベース URL。ドキュメントの場所を示すために使用されます。 Canonical Link Relation を使用します。

バージョン 1.8 で追加。

html_codeblock_linenos_style
型:
'inline' | 'table'
デフォルト:
'inline'

コードブロックの行番号のスタイル。

'table'

<table> タグを使用して行番号を表示します。

'inline'

<span> タグを使用して行番号を表示します。

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

バージョン 4.0 で変更: デフォルトは 'inline' です。

バージョン 4.0 で非推奨になりました。

html_context
型:
dict[str, Any]
デフォルト:
{}

すべてのページのテンプレートエンジンのコンテキストに渡す値の辞書。単一の値は、sphinx-build の --html-define コマンドラインオプションを使用してこの辞書に入れることもできます。

バージョン 0.5 で追加。

型:
str
デフォルト:
''

指定した場合、ドキュメントのロゴとなる画像ファイルの名前（設定ディレクトリからの相対パス）またはロゴの画像ファイルを指すURLである必要があります。これはサイドバーの上部に配置されるため、幅は200ピクセルを超えないようにする必要があります。

バージョン 0.4.1 で追加: 画像ファイルは _static ディレクトリにコピーされますが、そのファイルがまだ存在しない場合に限ります。

バージョン 4.0 で変更: URLも受け入れるようになりました。

html_favicon
型:
str
デフォルト:
''

指定した場合、ドキュメントのファビコンとなる画像ファイルの名前（設定ディレクトリからの相対パス）またはファビコンの画像ファイルを指すURLである必要があります。ブラウザはこれをタブ、ウィンドウ、ブックマークのアイコンとして使用します。PNG、SVG、GIF、またはICOファイル形式の16x16ピクセルのアイコンである必要があります。

例

html_favicon = 'static/favicon.png'

バージョン 0.4 で追加: 画像ファイルは _static にコピーされますが、そのファイルがまだ存在しない場合に限ります。

バージョン 4.0 で変更: ファビコンのURLも受け入れるようになりました。

html_css_files
型:
Sequence[str | tuple[str, dict[str, str]]]
デフォルト:
[]

CSSファイルのリスト。エントリは、filename 文字列、または filename 文字列と attributes 辞書を含むタプルである必要があります。filename は、html_static_pathからの相対パス、または 'https://example.org/style.css' のようなスキームを持つ完全なURIである必要があります。attributes 辞書は、<link> タグの属性に使用されます。

例

html_css_files = [
    'custom.css',
    'https://example.com/css/custom.css',
    ('print.css', {'media': 'print'}),
]

特別な属性である priority は、CSSファイルをより早くまたは遅くロードするための整数として設定できます。詳細については、Sphinx.add_css_file() を参照してください。

バージョン 1.8 で追加。

バージョン 3.5 で変更: priority 属性をサポート

html_js_files
型:
Sequence[str | tuple[str, dict[str, str]]]
デフォルト:
[]

JavaScriptファイルのリスト。エントリは、filename 文字列、または filename 文字列と attributes 辞書を含むタプルである必要があります。filename は、html_static_pathからの相対パス、または 'https://example.org/script.js' のようなスキームを持つ完全なURIである必要があります。attributes 辞書は、<script> タグの属性に使用されます。

例

html_js_files = [
    'script.js',
    'https://example.com/scripts/custom.js',
    ('custom.js', {'async': 'async'}),
]

特別な属性として、priority は、JavaScriptファイルをより早くまたは遅くロードするための整数として設定できます。詳細については、Sphinx.add_js_file() を参照してください。

バージョン 1.8 で追加。

バージョン 3.5 で変更: priority 属性をサポート

html_static_path
型:
list[str]
デフォルト:
[]

カスタム静的ファイル（スタイルシートやスクリプトファイルなど）を含むパスのリスト。相対パスは、設定ディレクトリからの相対パスとして扱われます。これらは、テーマの静的ファイルの後に、出力の _static ディレクトリにコピーされるため、default.css という名前のファイルは、テーマの default.css を上書きします。

これらのファイルはビルドされることを意図していないため、ソースファイルから自動的に除外されます。

注釈

セキュリティ上の理由から、html_static_path の下のドットファイルはコピーされません。意図的にコピーしたい場合は、この設定に各ファイルを明示的に追加してください。

html_static_path = ['_static', '_static/.htaccess']

別の方法として、html_extra_path を使用する方法があり、ディレクトリの下のドットファイルをコピーできます。

バージョン 0.4 で変更: html_static_path のパスにサブディレクトリを含めることができるようになりました。

バージョン 1.0 で変更: html_static_path のエントリを単一ファイルにすることができるようになりました。

バージョン 1.8 で変更: html_static_path の下のファイルはソースファイルから除外されます。

html_extra_path
型:
list[str]
デフォルト:
[]

robots.txt や .htaccess など、ドキュメントに直接関係のない追加ファイルを含むパスのリスト。相対パスは、設定ディレクトリからの相対パスとして扱われます。これらは出力ディレクトリにコピーされます。これらは、同じ名前の既存のファイルを上書きします。

これらのファイルはビルドされることを意図していないため、ソースファイルから自動的に除外されます。

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

バージョン 1.4 で変更: 追加ディレクトリ内のドットファイルが出力ディレクトリにコピーされるようになりました。また、追加のファイルやディレクトリをコピーする際に、exclude_patterns を参照し、パスがパターンに一致する場合は無視します。

html_last_updated_fmt
型:
str
デフォルト:
'%b %d, %Y'

設定した場合、「最終更新日：」タイムスタンプが、指定された strftime() 形式を使用してページフッターに挿入されます。空の文字列は、'%b %d, %Y' （またはロケール依存の同等のもの）と同じです。

型:
bool
デフォルト:
True

各見出しおよび説明環境にリンクアンカーを追加します。

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

型:
str
デフォルト:
'¶' (段落記号)

各見出しおよび説明環境のリンクアンカーのテキスト。HTMLエンティティとUnicodeが許可されます。

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

html_sidebars
型:
dict[str, Sequence[str]]
デフォルト:
{}

ドキュメント名をテンプレート名にマッピングする、カスタムサイドバーテンプレートを定義する辞書。

キーにはglobスタイルのパターンを含めることができ、その場合、一致するすべてのドキュメントに指定されたサイドバーが適用されます。（1つのドキュメントに対して複数のglobスタイルのパターンが一致した場合、警告が発行されます。）

各値は、含めるサイドバーテンプレートの完全なリストを指定する文字列のリストである必要があります。デフォルトのサイドバーの一部またはすべてを含める場合は、それらもこのリストに入れる必要があります。

（パターンに一致しないドキュメントの）デフォルトのサイドバーは、テーマ自体によって定義されます。組み込みテーマは、デフォルトでこれらのテンプレートを使用します：'localtoc.html'、'relations.html'、'sourcelink.html'、および'searchbox.html'。

バンドルされているサードパーティのサイドバーテンプレートでレンダリングできるものは次のとおりです。

  • localtoc.html - 現在のドキュメントの詳細な目次

  • globaltoc.html - ドキュメントセット全体の簡略化された目次、折りたたまれた状態

  • relations.html - 前のドキュメントと次のドキュメントへの2つのリンク

  • sourcelink.html - html_show_sourcelink で有効になっている場合は、現在のドキュメントのソースへのリンク

  • searchbox.html - 「クイック検索」ボックス

例

html_sidebars = {
   '**': ['globaltoc.html', 'sourcelink.html', 'searchbox.html'],
   'using/windows': ['windows-sidebar.html', 'searchbox.html'],
}

これにより、指定されたドキュメントのサイドバー内にカスタムテンプレート windows-sidebar.html とクイック検索ボックスがレンダリングされ、他のすべてのページにはデフォルトのサイドバーがレンダリングされます（ただし、ローカルTOCはグローバルTOCに置き換えられます）。

この値は、組み込みの scrolls および haiku テーマのように、選択したテーマにサイドバーがない場合は効果がないことに注意してください。

バージョン 1.0 で追加: globキーを使用し、複数のサイドバーを指定する機能。

バージョン 1.7 で非推奨: html_sidebars の単一の文字列値は削除されます。

バージョン 2.0 で変更: html_sidebars は文字列のリストである必要があり、単一の文字列値は受け入れなくなりました。

html_additional_pages
型:
dict[str, str]
デフォルト:
{}

HTMLページとしてレンダリングする必要のある追加のテンプレート。ドキュメント名をテンプレート名にマッピングする辞書である必要があります。

例

html_additional_pages = {
    'download': 'custom-download.html.jinja',
}

これにより、テンプレート custom-download.html.jinja がページ download.html としてレンダリングされます。

html_domain_indices
型:
bool | Sequence[str]
デフォルト:
True

Trueの場合、一般的なインデックスに加えて、ドメイン固有のインデックスを生成します。例えば、Pythonドメインでは、これはグローバルモジュールインデックスです。

この値は、ブール値または生成されるべきインデックス名のリストにすることができます。特定のインデックスのインデックス名を見つけるには、HTMLファイル名を見てください。例えば、Pythonモジュールインデックスの名前は'py-modindex'です。

例

html_domain_indices = {
    'py-modindex',
}

バージョン 1.0 で追加。

バージョン 7.4 で変更: set 型を許可し、推奨するようにしました。

html_use_index
型:
bool
デフォルト:
True

HTMLドキュメントにインデックスを追加するかどうかを制御します。

バージョン 0.4 で追加。

html_split_index
型:
bool
デフォルト:
False

インデックスの2つのバージョンを生成します。1つはすべてのエントリを含む単一ページとして、もう1つは開始文字ごとに1ページとして生成します。

バージョン 0.4 で追加。

html_copy_source
型:
bool
デフォルト:
True

Trueの場合、reStructuredTextソースはHTMLビルドに_sources/docnameとして含まれます。

型:
bool
デフォルト:
True

True（かつhtml_copy_sourceもTrueの場合）であれば、reStructuredTextソースへのリンクがサイドバーに追加されます。

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

型:
str
デフォルト:
'.txt'

ソースリンクに追加するサフィックス（html_show_sourcelinkを参照）、ファイルがすでにこのサフィックスを持っている場合は除く。

バージョン 1.5 で追加。

html_use_opensearch
型:
str
デフォルト:
''

空でない場合、OpenSearch記述ファイルが出力され、すべてのページにそれを参照する<link>タグが含まれます。OpenSearchは検索ページの場所に対して相対URLをサポートしていないため、このオプションの値は、これらのドキュメントが提供されるベースURL（末尾のスラッシュなし）である必要があります。例えば、'https://docs.python.org'です。

バージョン 0.2 で追加.

html_file_suffix
型:
str
デフォルト:
'.html'

生成されるHTMLファイルのファイル名サフィックス（ファイル拡張子）。

バージョン 0.4 で追加。

型:
str
デフォルト:
html_file_suffixの値

生成されたHTMLファイルへのリンクのサフィックス。より特殊なサーバー設定をサポートすることを目的としています。

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

型:
bool
デフォルト:
True

Trueの場合、HTMLフッターに「© Copyright …」と表示されます。値はcopyrightの値を使用します。

バージョン 1.0 で追加。

html_show_search_summary
型:
bool
デフォルト:
True

検索結果の概要、つまりキーワードの周辺のテキストを表示します。

バージョン 4.5 で追加.

html_show_sphinx
型:
bool
デフォルト:
True

HTMLフッターに「Sphinxを使用して作成」を追加します。

バージョン 0.4 で追加。

html_output_encoding
型:
str
デフォルト:
'utf-8'

HTML出力ファイルのエンコーディング。このエンコーディング名は、有効なPythonエンコーディング名であり、かつ有効なHTML charset値である必要があります。

バージョン 1.0 で追加。

html_compact_lists
型:
bool
デフォルト:
True

Trueの場合、すべての項目が単一の段落および/またはサブリストで構成されるリスト（再帰的定義）は、その項目のいずれにも<p>要素を使用しません。これは標準のdocutilsの動作です。デフォルト: True.

バージョン 1.0 で追加。

html_secnumber_suffix
型:
str
デフォルト:
'. '

HTML出力のセクション番号のサフィックス。セクション番号の最後のドットを抑制するには、' 'に設定します。

バージョン 1.0 で追加。

html_search_language
型:
str
デフォルト:
language の値

HTMLフルテキスト検索インデックスの生成に使用する言語。これはデフォルトでlanguageで選択されたグローバル言語になります。この言語がサポートされていない場合、フォールバックオプションとして英語（'en'）が使用されます。

次の言語がサポートされています

  • da – デンマーク語

  • nl – オランダ語

  • en – 英語

  • fi – フィンランド語

  • fr – フランス語

  • de – ドイツ語

  • hu – ハンガリー語

  • it – イタリア語

  • ja – 日本語

  • no – ノルウェー語

  • pt – ポルトガル語

  • ro – ルーマニア語

  • ru – ロシア語

  • es – スペイン語

  • sv – スウェーデン語

  • tr – トルコ語

  • zh – 中国語

ヒント

ビルド速度の加速

各言語（日本語を除く）は、独自のステミングアルゴリズムを提供します。SphinxはデフォルトでPython実装を使用します。インデックスファイルの構築を高速化したい場合は、pip install PyStemmerを実行して、サードパーティパッケージ（PyStemmer）を使用できます。

バージョン 1.1 で追加: 英語（en）と日本語（ja）をサポート。

バージョン 1.3 で変更: 追加の言語を追加。

html_search_options
型:
dict[str, str]
デフォルト:
{}

検索言語サポートのオプションを含む辞書。これらのオプションの意味は、選択された言語によって異なります。現在、日本語と中国語のみがオプションをサポートしています。

日本語:
type – 使用するスプリッターの種類。

その他のオプションは、使用するスプリッターによって異なります。

'sphinx.search.ja.DefaultSplitter'

デフォルトで使用されるTinySegmenterアルゴリズム。

'sphinx.search.ja.MecabSplitter':

MeCabバインディング。このスプリッターを使用するには、'mecab' Pythonバインディングまたはダイナミックリンクライブラリ（Linuxの場合は'libmecab.so'、Windowsの場合は'libmecab.dll'）が必要です。

'sphinx.search.ja.JanomeSplitter':

Janomeバインディング。このスプリッターを使用するには、Janomeが必要です。

バージョン 1.6 で非推奨: 'mecab'、'janome'、'default'は非推奨です。互換性を維持するために、'mecab'、'janome'、'default'も使用可能です。

'mecab'のオプション
dic_enc:

dic_encオプションは、MeCabアルゴリズムのエンコーディングです。

dict:

dictオプションは、MeCabアルゴリズムに使用する辞書です。

lib:

libオプションは、Pythonバインディングがインストールされていない場合に、ctypes経由でMeCabライブラリを見つけるためのライブラリ名です。

例

html_search_options = {
    'type': 'mecab',
    'dic_enc': 'utf-8',
    'dict': '/path/to/mecab .dic',
    'lib': '/path/to/libmecab.so',
}
'janome'のオプション
user_dic:

user_dicオプションは、Janomeのユーザー辞書ファイルのパスです。

user_dic_enc:

user_dic_encオプションは、user_dicオプションで指定されたユーザー辞書ファイルのエンコーディングです。デフォルトは「utf8」です。

中国語:
dict

カスタム辞書を使用するためのjieba辞書パス。

バージョン 1.1 で追加。

バージョン 1.4 で変更: 日本語のtype設定で、任意のカスタムスプリッターを許可する。

html_search_scorer
型:
str
デフォルト:
''

検索結果のスコアラーを実装するJavaScriptファイルの名前（設定ディレクトリからの相対パス）。空の場合は、デフォルトが使用されます。

スコアラーは次のインターフェースを実装する必要があり、より詳細な制御のためにscore()関数を任意に定義できます。

const Scorer = {
    // Implement the following function to further tweak the score for each result
    score: result => {
      const [docName, title, anchor, descr, score, filename] = result

      // ... calculate a new score ...
      return score
    },

    // query matches the full name of an object
    objNameMatch: 11,
    // or matches in the last dotted part of the object name
    objPartialMatch: 6,
    // Additive scores depending on the priority of the object
    objPrio: {
      0: 15, // used to be importantResults
      1: 5, // used to be objectResults
      2: -5, // used to be unimportantResults
    },
    //  Used when the priority is not in the mapping.
    objPrioDefault: 0,

    // query found in title
    title: 15,
    partialTitle: 7,

    // query found in terms
    term: 5,
    partialTerm: 2,
};

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

型:
bool
デフォルト:
True

スケールオプション（scale、width、またはheight）を使用してサイズ変更された画像を、元のフル解像度画像にリンクします。これは、imageディレクティブのtargetオプションで指定されたリンクが存在する場合は、上書きしません。

ヒント

画像ごとにこの機能を無効にするには、画像ディレクティブにno-scaled-linkクラスを追加します。

.. image:: sphinx.png
   :scale: 50%
   :class: no-scaled-link

バージョン 1.3 で追加。

バージョン 3.0 で変更: no-scaled-linkクラスを持つ画像はリンクされません。

html_math_renderer
型:
str
デフォルト:
'mathjax'

HTML出力に使用する数式レンダラー。バンドルされているレンダラーはmathjaxとimgmathです。extensionsで関連する拡張機能もロードする必要があります。

バージョン 1.8 で追加。

単一HTML出力のオプション

これらのオプションは、単一のHTML出力に影響します。このビルダーはHTMLビルダーから派生しているため、HTMLオプションも適宜適用されます。

singlehtml_sidebars
型:
dict[str, Sequence[str]]
デフォルト:
html_sidebarsの値

ドキュメント名をテンプレート名にマッピングする、カスタムサイドバーテンプレートを定義する辞書。

これは、html_sidebarsと同じ効果を持ちますが、許可されているキーは'index'のみであり、他のすべてのキーは無視されます。

HTMLヘルプ出力のオプション

これらのオプションは、HTMLヘルプ出力に影響します。このビルダーはHTMLビルダーから派生しているため、HTMLオプションも適宜適用されます。

htmlhelp_basename
型:
str
デフォルト:
'{project}doc'

HTMLヘルプビルダーの出力ファイルベース名。デフォルトは、スペースが削除されdocが付加されたproject nameです。

htmlhelp_file_suffix
型:
str
デフォルト:
'.html'

これは、生成されたHTMLヘルプファイルのファイル名サフィックスです。

バージョン 2.0 で追加。

型:
str
デフォルト:
htmlhelp_file_suffixの値

HTMLファイルへの生成されたリンクのサフィックス。

バージョン 2.0 で追加。

Apple Help出力のオプション

バージョン 1.3 で追加。

これらのオプションは、Apple Help出力に影響します。このビルダーはHTMLビルダーから派生しているため、HTMLオプションも適宜適用されます。

注釈

Apple Help出力は、Mac OS X 10.6以降でのみ動作します。これは、hiutilとcodesignコマンドラインツールが必要であり、どちらもオープンソースではないためです。

applehelp_disable_external_toolsを使用してこれらのツールの使用を無効にできますが、バンドル内の.lprojディレクトリでインデクサーが実行されるまで、結果は有効なヘルプブックにはなりません。

applehelp_bundle_name
型:
str
デフォルト:
projectの値

Apple Help Bookのベース名。デフォルトは、スペースが削除されたproject nameです。

applehelp_bundle_id
型:
str
デフォルト:
None

ヘルプブックバンドルのバンドルID。

警告

Apple Helpを生成するには、この値を設定する必要があります。

applehelp_bundle_version
型:
str
デフォルト:
'1'

文字列としてのバンドルバージョン。

applehelp_dev_region
型:
str
デフォルト:
'en-us'

開発リージョン。デフォルトは、Appleの推奨設定である'en-us'です。

applehelp_icon
型:
str
デフォルト:
None

ヘルプバンドルアイコンファイルへのパス、またはアイコンがない場合はNone。Appleのドキュメントによると、これはアプリケーションのアイコンの16x16ピクセルバージョンで、背景が透明で、PNGファイルとして保存されている必要があります。

applehelp_kb_product
型:
str
デフォルト:
'project-release'

applehelp_kb_urlで使用する製品タグ。

applehelp_kb_url
型:
str
デフォルト:
None

ナレッジベースサーバーのURL。例えば、https://example.com/kbsearch.py?p='product'&q='query'&l='lang'のように指定します。実行時、ヘルプビューアは'product'をapplehelp_kb_productの内容に、'query'をユーザーが検索ボックスに入力したテキストに、'lang'をユーザーのシステム言語に置き換えます。

リモート検索を無効にするには、これをNoneに設定します。

applehelp_remote_url
型:
str
デフォルト:
None

リモートコンテンツのURL。ヘルプブックのResourcesディレクトリのコピーをこの場所に配置でき、ヘルプビューアはそれを使用して更新されたコンテンツをフェッチしようとします。

たとえば、https://example.com/help/Foo/に設定した場合、ヘルプビューアが英語を話す顧客向けにindex.htmlのコピーを必要とする場合、https://example.com/help/Foo/en.lproj/index.htmlを探します。

リモートコンテンツを使用しない場合は、これをNoneに設定します。

applehelp_index_anchors
型:
bool
デフォルト:
False

生成されたHTMLのアンカーをインデックス化するようにヘルプインデクサーに指示します。これは、AHLookupAnchor関数またはコード内のopenHelpAnchor:inBook:メソッドを使用して、特定のトピックにジャンプする場合に役立ちます。また、help:anchor URLを使用することもできます。このトピックの詳細については、Appleのドキュメントを参照してください。

applehelp_min_term_length
型:
str
デフォルト:
None

ヘルプインデクサーの最小ターム長を制御します。Noneの場合、デフォルトの長さを使用します。

applehelp_stopwords
型:
str
デフォルト:
language の値

言語仕様（組み込みのストップワードを使用する場合）、ストップワードplistへのパス、またはストップワードを使用しない場合はNoneのいずれか。デフォルトのストップワードplistは/usr/share/hiutil/Stopwords.plistにあり、執筆時点では次の言語のストップワードが含まれています。

  • ドイツ語（de）

  • 英語（en）

  • スペイン語（es）

  • フランス語（fr）

  • ハンガリー語（hu）

  • イタリア語（it）

  • スウェーデン語（sv）

applehelp_locale
型:
str
デフォルト:
language の値

ヘルプを生成するロケールを指定します。これは、ヘルプブックのResources内の.lprojディレクトリの名前を決定するために使用され、ヘルプインデクサーに渡されます。

applehelp_title
型:
str
デフォルト:
'project Help'

ヘルプブックのタイトルを指定します。

applehelp_codesign_identity
型:
str
デフォルト:
CODE_SIGN_IDENTITYの値

コード署名に使用するIDを指定します。コード署名を実行しない場合は、Noneを使用します。

デフォルトは、スクリプトビルドフェーズでXcodeによって設定されるCODE_SIGN_IDENTITY環境変数の値、またはその変数が設定されていない場合はNoneです。

applehelp_codesign_flags
型:
list[str]
デフォルト:
OTHER_CODE_SIGN_FLAGSの値

ヘルプブックに署名するときにcodesignに渡す追加の引数のリスト。

デフォルトは、スクリプトビルドフェーズでXcodeによって設定されるOTHER_CODE_SIGN_FLAGS環境変数の値に基づくリスト、またはその変数が設定されていない場合は空のリストです。

applehelp_codesign_path
型:
str
デフォルト:
'/usr/bin/codesign'

codesignプログラムへのパス。

applehelp_indexer_path
型:
str
デフォルト:
'/usr/bin/hiutil'

hiutilプログラムへのパス。

applehelp_disable_external_tools
型:
bool
デフォルト:
False

他の設定がどのように指定されていても、インデクサーやコード署名ツールを実行しません。

これは主にテストに役立ちます。または、何らかの理由でmacOS以外のプラットフォームでSphinxビルドを実行し、最終的なステップをMacで完了したい場合に役立ちます。

EPUB出力のオプション

これらのオプションはEPUB出力に影響を与えます。このビルダーはHTMLビルダーから派生しているため、HTMLオプションも適切に適用されます。

注釈

これらのオプションの一部の実際の値は重要ではありませんが、ダブリンコアメタデータには必須です。

epub_basename
型:
str
デフォルト:
projectの値

EPUBファイルのベース名。

epub_theme
型:
str
デフォルト:
'epub'

EPUB出力用のHTMLテーマ。デフォルトのテーマは小さな画面スペース用に最適化されていないため、HTMLとEPUBの出力に同じテーマを使用することは通常賢明ではありません。デフォルトは、視覚的なスペースを節約するように設計されたテーマである'epub'です。

epub_theme_options
型:
dict[str, Any]
デフォルト:
{}

選択したテーマのデザインに影響を与えるオプションの辞書。これらはテーマ固有です。組み込みテーマで理解されるオプションについては、こちらで説明しています。

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

epub_title
型:
str
デフォルト:
projectの値

ドキュメントのタイトル。

バージョン 2.0 で変更: projectオプションがデフォルトになりました（以前はhtml_titleでした）。

epub_description
型:
str
デフォルト:
'不明'

ドキュメントの説明。

バージョン 1.4 で追加。

バージョン 1.5 で変更: epub3_descriptionから名前が変更されました。

epub_author
型:
str
デフォルト:
authorの値

ドキュメントの作者。これはダブリンコアメタデータに入れられます。

epub_contributor
型:
str
デフォルト:
'不明'

EPUB出版物のコンテンツの作成に二次的な役割を果たした個人、組織などの名前。

バージョン 1.4 で追加。

バージョン 1.5 で変更: epub3_contributorから名前が変更されました。

epub_language
型:
str
デフォルト:
language の値

ドキュメントの言語。これはダブリンコアメタデータに入れられます。

epub_publisher
型:
str
デフォルト:
authorの値

ドキュメントの発行者。これはダブリンコアメタデータに入れられます。プロジェクトのホームページなど、任意の適切な文字列を使用できます。

型:
str
デフォルト:
copyrightの値

ドキュメントの著作権。

epub_identifier
型:
str
デフォルト:
'不明'

ドキュメントの識別子。これはダブリンコアメタデータに入れられます。公開されたドキュメントの場合、これはISBN番号ですが、プロジェクトのホームページなど、別のスキームを使用することもできます。

epub_scheme
型:
str
デフォルト:
'不明'

epub_identifierの公開スキーム。これはダブリンコアメタデータに入れられます。公開された書籍の場合、スキームは'ISBN'です。プロジェクトのホームページを使用する場合、'URL'が妥当と思われます。

epub_uid
型:
str
デフォルト:
'不明'

ドキュメントの一意の識別子。これはダブリンコアメタデータに入れられます。XMLのName形式の文字列を使用できます。最初の文字としてハイフン、ピリオド、数字を使用することはできません。

epub_cover
型:
tuple[str, str]
デフォルト:
()

表紙の情報。これは、表紙画像とHTMLテンプレートのファイル名を含むタプルです。レンダリングされたHTML表紙ページは、content.opfのスパインの最初の項目として挿入されます。テンプレートファイル名が空の場合、HTML表紙ページは作成されません。タプルが空の場合、表紙はまったく作成されません。

例

epub_cover = ('_static/cover.png', 'epub-cover.html')
epub_cover = ('_static/cover.png', '')
epub_cover = ()

バージョン 1.1 で追加。

epub_css_files
型:
Sequence[str | tuple[str, dict[str, str]]]
デフォルト:
[]

CSSファイルのリスト。エントリは、ファイル名文字列、またはファイル名文字列と属性ディクショナリを含むタプルである必要があります。ファイル名は、html_static_pathからの相対パス、または'https://example.org/style.css'のようなスキーム付きの完全なURIである必要があります。属性ディクショナリは、<link>タグの属性に使用されます。詳細については、html_css_filesを参照してください。

バージョン 1.8 で追加。

epub_guide
型:
Sequence[tuple[str, str, str]]
デフォルト:
()

content.opfのguide要素のメタデータ。これは、オプションのガイド情報のtype、uri、およびtitleを含むタプルのシーケンスです。詳細については、OPFドキュメントを参照してください。可能であれば、coverおよびtocタイプのデフォルトエントリが自動的に挿入されます。ただし、デフォルトのエントリが適切でない場合は、タイプを明示的に上書きできます。

例

epub_guide = (
    ('cover', 'cover.html', 'Cover Page'),
)

デフォルト値は()です。

epub_pre_files
型:
Sequence[tuple[str, str]]
デフォルト:
()

Sphinxによって生成されたテキストの前に挿入する必要がある追加ファイル。これは、ファイル名とタイトルを含むタプルのリストです。タイトルが空の場合、toc.ncxにエントリは追加されません。

例

epub_pre_files = [
    ('index.html', 'Welcome'),
]
epub_post_files
型:
Sequence[tuple[str, str]]
デフォルト:
()

Sphinxによって生成されたテキストの後に挿入する必要がある追加ファイル。これは、ファイル名とタイトルを含むタプルのリストです。このオプションは、付録を追加するために使用できます。タイトルが空の場合、toc.ncxにエントリは追加されません。

例

epub_post_files = [
    ('appendix.xhtml', 'Appendix'),
]
epub_exclude_files
型:
Sequence[str]
デフォルト:
[]

ビルドディレクトリで生成/コピーされるが、EPUBファイルに含めるべきではないファイルのシーケンス。

epub_tocdepth
型:
int
デフォルト:
3

ファイルtoc.ncxの目次の深さ。これはゼロより大きい整数である必要があります。

ヒント

深くネストされた目次はナビゲートが難しい場合があります。

epub_tocdup
型:
bool
デフォルト:
True

このフラグは、ネストされた目次リストの先頭に目次エントリが再度挿入されるかどうかを決定します。これにより、章の先頭へのナビゲーションが容易になりますが、1つのリストに異なる深さのエントリが混在するため、混乱する可能性があります。

epub_tocscope
型:
'default' | 'includehidden'
デフォルト:
'default'

この設定は、EPUB目次の範囲を制御します。設定には次の値を指定できます

'default'

非表示になっていないすべての目次エントリを含めます

'includehidden'

すべての目次エントリを含めます

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

epub_fix_images
型:
bool
デフォルト:
False

一部のEPUBリーダーでサポートされていない画像形式を修正しようとします。現時点では、小さなカラーテーブルを持つパレット画像がアップグレードされます。自動変換によって情報が失われる可能性があるため、これはデフォルトで無効になっています。このオプションを使用するには、Python Image Library（Pillow）をインストールする必要があります。

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

epub_max_image_width
型:
int
デフォルト:
0

このオプションは、画像の最大幅を指定します。ゼロより大きい値に設定すると、指定された値よりも幅が大きい画像はそれに応じて拡大縮小されます。ゼロの場合、拡大縮小は実行されません。このオプションを使用するには、Python Image Library（Pillow）をインストールする必要があります。

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

epub_show_urls
型:
'footnote' | 'no' | 'inline'
デフォルト:
'footnote'

URLアドレスの表示方法を制御します。これは、リンクされたURLを表示する他の手段がないリーダーにとって非常に役立ちます。設定には次の値を指定できます

'inline'

URLを括弧で囲んでインライン表示します。

'footnote'

URLを脚注に表示します。

'no'

URLを表示しません。

インラインURLの表示は、クラスlink-targetのCSSルールを追加することでカスタマイズできます。

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

epub_use_index
型:
bool
デフォルト:
html_use_indexの値

EPUBドキュメントにインデックスを追加します。

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

epub_writing_mode
型:
'horizontal' | 'vertical'
デフォルト:
'horizontal'

記述方向を指定します。 'horizontal' と 'vertical' を受け入れます。

epub_writing_mode

'horizontal'

'vertical'

writing-mode

horizontal-tb

vertical-rl

ページの進行方向

左から右

右から左

iBookのスクロールテーマのサポート

scroll-axis は垂直です。

scroll-axis は水平です。

LaTeX出力のオプション

これらのオプションはLaTeX出力に影響します。

latex_engine
型:
'pdflatex' | 'xelatex' | 'lualatex' | 'platex' | 'uplatex'
デフォルト:
'pdflatex'

ドキュメントをビルドするLaTeXエンジン。設定値は以下のいずれかです。

  • 'pdflatex' – PDFLaTeX（デフォルト）

  • 'xelatex' – XeLaTeX

  • 'lualatex' – LuaLaTeX

  • 'platex' – pLaTeX

  • 'uplatex' – upLaTeX（language が 'ja' の場合のデフォルト）

重要

'pdflatex' のUnicode文字のサポートは限定的です。プロジェクトでUnicode文字を使用している場合、エンジンを 'xelatex' または 'lualatex' に設定し、十分なグリフ範囲を持つOpenTypeフォントを使用するようにするのが、 'pdflatex' で追加のUnicode文字を動作させようとするよりも簡単な場合があります。 Sphinx 2.0以降、デフォルトの書体はGNU FreeFontであり、ラテン文字、キリル文字、ギリシャ文字のグリフを適切にカバーしています。

注釈

Sphinx 2.0では、ラテン語を使用するドキュメントで、 'pdflatex' を使用する場合に、キリル文字やギリシャ文字の文字や単語が散在する場合のサポートが追加されました。これを有効にするには、'fontenc' キーを latex_elements で適切に使用する必要があります。

注釈

HTML出力でのMathJaXによる数式レンダリング とは対照的に、LaTeXでは、math でUnicodeリテラルをサポートするために、いくつかの追加設定が必要です。（私たちが知る限り）唯一の包括的な解決策は、 'xelatex' または 'lualatex' を使用する*とともに*、r'\usepackage{unicode-math}' を追加することです（例えば、'preamble' キーを latex_elements を経由します）。 α (U+03B1)のようなUnicodeリテラルを \(\alpha\) としてレンダリングするのではなく、出力でそのまま保持するために r'\usepackage[math-style=literal]{unicode-math}' を優先するかもしれません。

バージョン 2.1.0 で変更: 中国語ドキュメントの場合、デフォルトで 'xelatex' （およびLaTeXパッケージ xeCJK ）を使用するように変更されました。

バージョン 2.2.1 で変更: ギリシャ語ドキュメントの場合、デフォルトで 'xelatex' を使用するように変更されました。

バージョン 2.3 で変更: 'uplatex' のサポートを追加しました。

バージョン 4.0 で変更: 日本語ドキュメントの場合、デフォルトで 'uplatex' を使用するように変更されました。

latex_documents
型:
Sequence[tuple[str, str, str, str, str, bool]]
デフォルト:
デフォルトのLaTeXドキュメント

この値は、ドキュメントツリーをLaTeXソースファイルにグループ化する方法を決定します。これは、タプルのリスト (startdocname, targetname, title, author, theme, toctree_only) である必要があり、項目の内容は以下のとおりです。

startdocname

LaTeXファイルのマスタードキュメントのドキュメント名を指定する文字列。 ToCツリー内の*startdoc*ドキュメントによって参照されるすべてのドキュメントがLaTeXファイルに含まれます。（LaTeXビルドにデフォルトのマスタードキュメントを使用する場合は、ここでmaster_doc を指定してください。）

targetname

出力ディレクトリ内のLaTeXファイルのファイル名。

title

LaTeXドキュメントのタイトル。 *startdoc* ドキュメントのタイトルを使用するために空にできます。これはLaTeXマークアップとして挿入されるため、バックスラッシュやアンパサンドのような特殊文字は、文字通り挿入される場合は適切なLaTeXコマンドで表現する必要があります。

author

LaTeXドキュメントの著者。*title*と同じLaTeXマークアップの注意が適用されます。複数の著者には、\\and を使用して区切ります。例： 'John \\and Sarah' （バックスラッシュはLaTeXに到達するためにPythonエスケープする必要があります）。

theme

LaTeXテーマ。latex_theme を参照してください。

toctree_only

True または False である必要があります。Trueの場合、*startdoc*ドキュメント自体は出力に含まれず、ToCツリーによって参照されるドキュメントのみが含まれます。このオプションを使用すると、HTMLには表示されるがLaTeX出力には表示されない追加の内容をマスタードキュメントに記述できます。

バージョン 0.3 で追加: 6番目の項目 toctree_only。5つの項目を含むタプルも受け入れられます。

バージョン 1.2 で追加: 以前は、独自のドキュメントクラスを含めるには、ドキュメントクラス名の前に文字列 "sphinx" を追加する必要がありました。これはもう必要ありません。

型:
str
デフォルト:
''

指定した場合、これはドキュメントのロゴとなる画像ファイルの名前（設定ディレクトリからの相対パス）である必要があります。タイトルページの上部に配置されます。

latex_toplevel_sectioning
型:
'part' | 'chapter' | 'section'
デフォルト:
None

この値は、最上位のセクション単位を決定します。デフォルト設定は、latex_theme が 'howto' の場合は 'section' で、'manual' の場合は 'chapter' です。どちらの場合も、代わりに 'part' を指定することができます。これは、LaTeXドキュメントが \part コマンドを使用することを意味します。

その場合、1レベル下のセクション単位の番号はHTML番号と同期しなくなります。これは、LaTeXがデフォルトで \chapter の番号（または 'howto' テーマの場合には \section ）を \part コマンドに遭遇したときにリセットしないためです。

バージョン 1.4 で追加。

latex_appendices
型:
Sequence[str]
デフォルト:
()

すべてのマニュアルの付録として追加するドキュメント名のリスト。 latex_theme が 'howto' に設定されている場合は無視されます。

latex_domain_indices
型:
bool | Sequence[str]
デフォルト:
True

Trueの場合、一般的なインデックスに加えて、ドメイン固有のインデックスを生成します。例えば、Pythonドメインでは、これはグローバルモジュールインデックスです。

この値は、ブール値または生成されるべきインデックス名のリストにすることができます。特定のインデックスのインデックス名を見つけるには、HTMLファイル名を見てください。例えば、Pythonモジュールインデックスの名前は'py-modindex'です。

例

latex_domain_indices = {
    'py-modindex',
}

バージョン 1.0 で追加。

バージョン 7.4 で変更: set 型を許可し、推奨するようにしました。

latex_show_pagerefs
型:
bool
デフォルト:
False

内部参照の後にページ参照を追加します。これは、マニュアルの印刷コピーに非常に役立ちます。

バージョン 1.0 で追加。

latex_show_urls
型:
'no' | 'footnote' | 'inline'
デフォルト:
'no'

URLアドレスの表示方法を制御します。これはマニュアルの印刷版で非常に役立ちます。この設定には次の値を設定できます。

'no'

URLを表示しない

'footnote'

URLを脚注に表示する

'inline'

URLを括弧付きでインライン表示する

バージョン 1.0 で追加。

バージョン 1.1 で変更: この値は文字列になりました。以前はブール値であり、true の値は 'inline' 表示を選択していました。後方互換性のために、True は引き続き受け入れられます。

latex_use_latex_multicolumn
型:
bool
デフォルト:
False

テーブルのマージされたセルに標準の LaTeX の \multicolumn を使用します。

False

Sphinx 独自のマクロは、グリッドテーブルのマージされたセルに使用されます。これらは一般的な内容 (リテラルブロック、リスト、引用文など) を許可しますが、tabularcolumns ディレクティブを使用して、>{..}、<{..}、@{..} のような LaTeX マークアップを列指定として挿入した場合に問題が発生する可能性があります。

True

LaTeX の標準の \multicolumn を使用します。これは、水平方向にマージされたセルのリテラルブロックと互換性がなく、テーブルが tabulary を使用してレンダリングされる場合、そのようなセル内の複数の段落とも互換性がありません。

バージョン 1.6 で追加。

latex_table_style
型:
list[str]
デフォルト:
['booktabs', 'colorrows']

スタイルクラス（文字列）のリスト。現在サポートされているもの：

'booktabs'

縦線がなく、水平線は2本または3本（ヘッダーがある場合は後者）、booktabs パッケージを使用します。

'borderless'

線は一切ありません。

'colorrows'

テーブルの行は、交互の背景色でレンダリングされます。これらをカスタマイズするためのインターフェースは、専用キー （sphinxsetup 設定）を介して行います。

重要

'colorrows' スタイルを使用すると、\rowcolors LaTeX コマンドは no-op になります (このコマンドには制限があり、Sphinx が LaTeX で生成するすべてのタイプのテーブルを正しくサポートしたことはありません)。代わりに、latex テーブルの色構成キーを使用するようにプロジェクトを更新してください。

各テーブルは、:class: オプション、または非ディレクティブテーブルの場合は .. rst-class:: を介してグローバルスタイルを上書きできます（テーブルを参照）。現在認識されているクラスは、booktabs、borderless、standard、colorrows、nocolorrows です。後者の 2 つは、最初の 3 つのいずれかと組み合わせることができます。standard クラスは、水平線と垂直線の両方を持つテーブルを生成します（これは、これまでの Sphinx のデフォルトでした）。

単一行の複数列マージされたセルは、行の色が設定されている場合、行の色に従います。sphinxsetup 設定セクションのTableMergeColor{Header,Odd,Even}も参照してください。

注釈

  • 単一のセルは、列指定からの \columncolor を介して列の色が設定されている場合でも、行の色に従うことは LaTeX でハードコーディングされています（tabularcolumnsを参照）。Sphinx は、次のようにテーブル列の指定で使用できる \sphinxnorowcolor を提供します。

    >{\columncolor{blue}\sphinxnorowcolor}

  • Sphinx は \sphinxcolorblend も提供しますが、これには xcolor パッケージが必要です。例を次に示します。

    >{\sphinxcolorblend{!95!red}}

    これは、この列では、行の色が赤でわずかに着色されることを意味します。 \blendcolors コマンドの構文の詳細については、xcolor のドキュメントを参照してください（\sphinxcolorblend の代わりに \blendcolors を使用すると、セルの背景色パネルではなく、セルの内容の色が変更されます…）。PDF 形式のこのドキュメントの非推奨 APIセクションで使用例を見つけることができます。

    ヒント

    特定の列のセルの内容に特別な色を使用する場合は、上記の追加の可能性に加えて、>{\noindent\color{<color>}}を使用します。

  • 単一列であろうと複数列であろうと、複数行のマージされたセルは、設定された列、行、またはセルの色を現在無視します。

  • 単純なセルでは、rawディレクティブと、セルコンテンツ内の任意の場所で使用される \cellcolor LaTeX コマンドを介してカスタム色を設定できます。これは、マージされたセルでは、その種類に関係なく、現在効果がありません。

ヒント

グローバルに 'booktabs' を使用しないドキュメントでは、個々のテーブルを booktabs クラスを使用してスタイル設定できますが、LaTeX プリアンブルに r'\usepackage{booktabs}' を追加する必要があります。

一方、個々のテーブルに colorrows クラスを、追加のパッケージなしで使用できます（Sphinx 5.3.0 以降、常に colortbl をロードするため）。

バージョン 5.3.0 で追加。

バージョン 6.0.0 で変更: デフォルトを [] から ['booktabs', 'colorrows'] に変更。

latex_use_xindy
型:
bool
デフォルト:
latex_engine in {'xelatex', 'lualatex'} の場合 True それ以外の場合 False

一般的な用語の索引を作成するために、Xindy を使用します。デフォルトでは、LaTeX ビルダーは一般的な用語の索引を作成するためにmakeindex を使用します。Xindy を使用すると、UTF-8 文字を含む単語がlanguageに対して正しく順序付けられます。

  • latex_engine が 'platex' (日本語ドキュメント; mendex が makeindex に取って代わる) の場合、このオプションは無視されます。

  • デフォルトは、makeindex が、インデックス付き用語が ASCII 以外の文字で始まる場合に、UTF-8 エンコードに無効なバイトを含む .ind ファイルを作成するため、'xelatex' または 'lualatex' の場合は True です。'lualatex' では、これにより PDF ビルドが中断します。

  • デフォルトは 'pdflatex' の場合は False ですが、一部のインデックス付き用語が言語スクリプトの ASCII 以外の文字を使用する場合は、英語以外のドキュメントでは True が推奨されます。

Sphinx は、キリル文字スクリプトで 'pdflatex' エンジンを使用するための xindy ベースディストリビューションに対する専用のサポートを追加しています。'pdflatex' エンジンと Unicode エンジンのどちらを使用しても、キリル文字ドキュメントでは、発音区別符号付きのものを含め、ラテン文字の名前のインデックスが正しく処理されます。

バージョン 1.8 で追加。

latex_elements
型:
dict[str, str]
デフォルト:
{}

バージョン 0.5 で追加。

latex_elements の完全なドキュメントを参照してください。.

latex_docclass
型:
dict[str, str]
デフォルト:
{}

'howto' および 'manual' を、2 つの Sphinx クラスのベースとして使用される実際のドキュメントクラスの名前にマッピングする辞書。デフォルトでは、'howto' には 'article'、'manual' には 'report' が使用されます。

バージョン 1.0 で追加。

バージョン 1.5 で変更: 日本語ドキュメント (language が 'ja' の場合) では、デフォルトで 'howto' には 'jreport' が、'manual' には 'jsbook' が使用されます。

latex_additional_files
型:
Sequence[str]
デフォルト:
()

LaTeX 出力をビルドする際に、設定ディレクトリからの相対パスで、ビルドディレクトリにコピーするファイル名のリスト。これは、Sphinx が自動的にコピーしないファイルをコピーしたり、Sphinx の LaTeX サポートファイルをカスタムバージョンで上書きしたりするのに便利です。ソースファイルで参照されている画像ファイル (例: .. image:: を使用) は自動的にコピーされるため、ここにリストしないでください。

注意

.tex 拡張子のファイル名は、sphinx-build -M latexpdf または make latexpdf によってトリガーされる PDF ビルドプロセスに自動的に引き渡されます。ファイルが変更されたプリアンブルから \input{} するためだけに追加された場合は、ファイル名に .txt などの追加のサフィックスを追加し、それに応じて \input{} マクロを調整する必要があります。

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

バージョン 1.2 で変更: これは sphinx.sty など、Sphinx から提供されるファイルを上書きします。

latex_theme
型:
str
デフォルト:
'manual'

LaTeX 出力で使用する「テーマ」。これは、LaTeX 出力の設定 (ドキュメントクラス、最上位セクション単位など) のコレクションです。

バンドルされているファーストパーティの LaTeX テーマは、manual と howto です。

manual

マニュアルを作成するための LaTeX テーマ。report ドキュメントクラスをインポートします (日本語ドキュメントでは jsbook を使用)。

howto

記事を作成するための LaTeX テーマ。article ドキュメントクラスをインポートします (日本語ドキュメントでは jreport を使用)。latex_appendices は、このテーマでのみ使用可能です。

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

latex_theme_options
型:
dict[str, Any]
デフォルト:
{}

選択したテーマのルックアンドフィールに影響を与えるオプションの辞書。これらはテーマ固有です。

バージョン 3.1 で追加。

latex_theme_path
型:
list[str]
デフォルト:
[]

カスタム LaTeX テーマがサブディレクトリとして含まれるパスのリスト。相対パスは、設定ディレクトリからの相対パスとして扱われます。

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

テキスト出力のオプション

これらのオプションは、テキスト出力に影響を与えます。

text_add_secnumbers
型:
bool
デフォルト:
True

テキスト出力にセクション番号を含めます。

バージョン 1.7 で追加。

text_newlines
型:
'unix' | 'windows' | 'native'
デフォルト:
'unix'

テキスト出力で使用される改行文字を決定します。

'unix'

Unix スタイルの改行文字 (\n) を使用します。

'windows'

Windows スタイルの改行文字 (\r\n) を使用します。

'native'

ドキュメントがビルドされるプラットフォームの改行スタイルを使用します。

バージョン 1.1 で追加。

text_secnumber_suffix
型:
str
デフォルト:
'. '

テキスト出力のセクション番号のサフィックス。セクション番号の最後のドットを抑制するには、' ' に設定します。

バージョン 1.7 で追加。

text_sectionchars
型:
str
デフォルト:
'*=-~"+`'

セクションの下線を引くために使用する必要がある 7 文字の文字列。最初の文字は 1 レベルの見出し、2 番目の文字は 2 レベルの見出しなどに対して使用されます。

バージョン 1.1 で追加。

マニュアルページ出力のオプション

これらのオプションは、マニュアルページ出力に影響を与えます。

man_pages
型:
Sequence[tuple[str, str, str, str, str]]
デフォルト:
デフォルトのマニュアルページ

この値は、ドキュメントツリーをマニュアルページにグループ化する方法を決定します。これは、タプル (startdocname, name, description, authors, section) のリストである必要があります。ここで、各アイテムは

startdocname

マニュアルページのマスタードキュメントの ドキュメント名 を指定する文字列。ToC ツリー内の *startdoc* ドキュメントによって参照されるすべてのドキュメントが、マニュアルページに含まれます。(マニュアルページビルドにデフォルトのマスタードキュメントを使用する場合は、ここに master_doc を指定します。)

name

マニュアルページの名前。これは、スペースや特殊文字を含まない短い文字列である必要があります。ファイル名とマニュアルページの名前 (NAME セクション) を決定するために使用されます。

description

マニュアルページの説明。これは NAME セクションで使用されます。NAME セクションを自動的に生成したくない場合は、空の文字列にすることができます。

authors

作者の文字列リスト、または 1 つの文字列。マニュアルページで AUTHORS セクションを自動的に生成したくない場合は、空の文字列またはリストにすることができます。

section

マニュアルページのセクション。出力ファイル名とマニュアルページヘッダーで使用されます。

バージョン 1.0 で追加。

man_show_urls
型:
bool
デフォルト:
False

リンクの後ろに URL アドレスを追加します。

バージョン 1.1 で追加。

man_make_section_directory
型:
bool
デフォルト:
True

マニュアルページをビルドする際に、セクションディレクトリを作成します。

バージョン 3.3 で追加。

バージョン 4.0 で変更: デフォルトは False になりました (以前は True でした)。

バージョン 4.0.2 で変更: デフォルトの変更を元に戻します。

Texinfo 出力のオプション

これらのオプションは、Texinfo 出力に影響を与えます。

texinfo_documents
型:
Sequence[tuple[str, str, str, str, str, str, str, bool]]
デフォルト:
デフォルトの Texinfo ドキュメント

この値は、ドキュメントツリーを Texinfo ソースファイルにグループ化する方法を決定します。これは、タプル (startdocname, targetname, title, author, dir_entry, description, category, toctree_only) のリストである必要があります。ここで、各アイテムは

startdocname

Texinfo ファイルのマスタードキュメントの ドキュメント名 を指定する文字列。ToC ツリー内の *startdoc* ドキュメントによって参照されるすべてのドキュメントが、Texinfo ファイルに含まれます。(Texinfo ビルドにデフォルトのマスタードキュメントを使用する場合は、ここに master_doc を指定します。)

targetname

出力ディレクトリ内の Texinfo ファイルのファイル名（拡張子なし）。

title

Texinfoドキュメントのタイトル。startdocドキュメントのタイトルを使用する場合は空にできます。Texinfoマークアップとして挿入されるため、@ や {} などの特殊文字をリテラルとして挿入するには、エスケープする必要があります。

author

Texinfoドキュメントの著者。Texinfoマークアップとして挿入されます。'John@*Sarah' のように、複数の著者を区切るには @* を使用します。

dir_entry

トップレベルの DIR メニューファイルに表示される名前。

description

トップレベルの DIR メニューファイルに表示される説明テキスト。

category

トップレベルの DIR メニューファイルにこのエントリが表示されるセクションを指定します。

toctree_only

True または False である必要があります。Trueの場合、startdocドキュメント自体は出力に含まれず、TOCツリーを介して参照されるドキュメントのみが含まれます。このオプションを使用すると、HTMLには表示されるが、Texinfo出力には表示されない追加のものをマスタードキュメントに入れることができます。

バージョン 1.1 で追加。

texinfo_appendices
型:
Sequence[str]
デフォルト:
[]

すべてのマニュアルの付録として追加するドキュメント名のリスト。

バージョン 1.1 で追加。

texinfo_cross_references
型:
bool
デフォルト:
True

ドキュメントにインライン参照を生成します。インライン参照を無効にすると、スタンドアロンリーダー（info）でinfoファイルをより読みやすくすることができます。

バージョン 4.4 で追加。

texinfo_domain_indices
型:
bool | Sequence[str]
デフォルト:
True

Trueの場合、一般的なインデックスに加えて、ドメイン固有のインデックスを生成します。例えば、Pythonドメインでは、これはグローバルモジュールインデックスです。

この値は、ブール値または生成されるべきインデックス名のリストにすることができます。特定のインデックスのインデックス名を見つけるには、HTMLファイル名を見てください。例えば、Pythonモジュールインデックスの名前は'py-modindex'です。

例

texinfo_domain_indices = {
    'py-modindex',
}

バージョン 1.1 で追加。

バージョン 7.4 で変更: set 型を許可し、推奨するようにしました。

texinfo_elements
型:
dict[str, Any]
デフォルト:
{}

Sphinxが通常生成された .texi ファイルに入れるTexinfoスニペットを上書きするTexinfoスニペットを含む辞書。

  • 上書きしたいキーには、以下が含まれます。

    'paragraphindent'

    各段落の最初の行をインデントするスペース数、デフォルトは 2。インデントなしにする場合は 0 を指定します。

    'exampleindent'

    例やリテラルブロックの行をインデントするスペース数、デフォルトは 4。インデントなしにする場合は 0 を指定します。

    'preamble'

    ファイルの先頭付近に挿入されるTexinfoマークアップ。

    'copying'

    @copying ブロック内に挿入され、タイトルの後に表示されるTexinfoマークアップ。デフォルト値は、プロジェクトを識別するシンプルなタイトルページで構成されています。

  • 他のオプションによって設定されるため、上書きすべきでないキーは、'author'、'body'、'date'、'direntry'、'filename'、'project'、'release'、および 'title' です。

バージョン 1.1 で追加。

texinfo_no_detailmenu
型:
bool
デフォルト:
False

ドキュメント内の各サブノードのエントリを含む「Top」ノードのメニューに @detailmenu を生成しません。

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

texinfo_show_urls
型:
'footnote' | 'no' | 'inline'
デフォルト:
'footnote'

URLアドレスの表示方法を制御します。この設定には次の値を指定できます。

'footnote'

URLを脚注に表示します。

'no'

URLを表示しません。

'inline'

URLを括弧で囲んでインライン表示します。

バージョン 1.1 で追加。

QtHelp出力のオプション

これらのオプションは、qthelp出力に影響します。このビルダーはHTMLビルダーから派生しているため、HTMLオプションも適切に適用されます。

qthelp_basename
型:
str
デフォルト:
projectの値

qthelpファイルのベース名。

qthelp_namespace
型:
str
デフォルト:
'org.sphinx.{project_name}.{project_version}'

qthelpファイルのネームスペース。

qthelp_theme
型:
str
デフォルト:
'nonav'

qthelp出力のHTMLテーマ。

qthelp_theme_options
型:
dict[str, Any]
デフォルト:
{}

選択したテーマのデザインに影響を与えるオプションの辞書。これらはテーマ固有です。組み込みテーマで理解されるオプションについては、こちらで説明しています。

XML出力のオプション

xml_pretty
型:
bool
デフォルト:
True

XMLをプリティプリントします。

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

linkcheckビルダーのオプション

フィルタリング

これらのオプションは、linkcheckビルダーがチェックするリンク、および無視する失敗とリダイレクトを制御します。

linkcheck_allowed_redirects
型:
dict[str, str]
デフォルト:
{}

ソースURIのパターンを正規のURIのパターンにマップする辞書。linkcheckビルダーは、以下の場合にリダイレクトされたリンクを「動作中」として扱います。

  • ドキュメント内のリンクがソースURIパターンと一致し、

  • リダイレクト先が正規のURIパターンと一致する場合。

linkcheckビルダーは、上記ルールを満たさないリダイレクトされたリンクを見つけると警告を発します。fail-on-warnings modeを使用する場合、予期しないリダイレクトを検出するのに役立ちます。

例

linkcheck_allowed_redirects = {
    # All HTTP redirections from the source URI to
    # the canonical URI will be treated as "working".
    r'https://sphinx-doc\.org/.*': r'https://sphinx-doc\.org/en/master/.*'
}

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

linkcheck_anchors
型:
bool
デフォルト:
True

リンク内の #anchor の有効性をチェックします。これにはドキュメント全体をダウンロードする必要があるため、有効にするとかなり遅くなります。

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

linkcheck_anchors_ignore
型:
Sequence[str]
デフォルト:
["^!"]

リンク内のアンカーの有効性をチェックする際に、linkcheckビルダーがスキップする必要があるアンカーに一致する正規表現のリスト。たとえば、これによりWebサイトのJavaScriptによって追加されたアンカーをスキップできます。

ヒント

URLをチェックするが、アンカーが存在することの検証をスキップする場合は、linkcheck_anchors_ignore_for_url を使用します。

注釈

特定のページまたは特定のパターンに一致するページのアンカーを無視する場合（ただし、アンカーのない同じページの出現をチェックする場合）は、代わりに linkcheck_ignore を使用します。たとえば、以下のようにします。

linkcheck_ignore = [
   'https://sphinx-doc.dokyumento.jp/en/1.7/intro.html#',
]

バージョン 1.5 で追加。

linkcheck_anchors_ignore_for_url
型:
Sequence[str]
デフォルト:
()

linkcheckビルダーがアンカーの有効性をチェックすべきでないURLに一致する正規表現のリストまたはタプル。これにより、ページ自体の有効性をチェックしながら、ページごとにアンカーチェックをスキップできます。

バージョン 7.1 で追加。

linkcheck_exclude_documents
型:
Sequence[str]
デフォルト:
()

linkcheckビルダーがリンクの有効性をチェックすべきでないドキュメントに一致する正規表現のリスト。これは、ドキュメントのレガシーセクションまたは過去のセクションでのリンクの劣化を許可するために使用できます。

例

# ignore all links in documents located in a subdirectory named 'legacy'
linkcheck_exclude_documents = [r'.*/legacy/.*']

バージョン 4.4 で追加。

linkcheck_ignore
型:
Sequence[str]
デフォルト:
()

linkcheck ビルドを実行するときにチェックすべきでないURIに一致する正規表現のリスト。

例

linkcheck_ignore = [r'https://localhost:\d+/']

バージョン 1.1 で追加。

HTTPリクエスト

これらのオプションは、linkcheckビルダーがリダイレクトと認証の処理方法、および使用するワーカーの数を含むHTTPリクエストを作成する方法を制御します。

linkcheck_auth
型:
Sequence[tuple[str, Any]]
デフォルト:
[]

linkcheck ビルドを実行するときに認証情報を渡します。

(regex_pattern, auth_info) タプルのリスト。アイテムは以下のとおりです。

regex_pattern

URIに一致する正規表現。

auth_info

そのURIに使用する認証情報。値は、requests ライブラリで理解できるものであれば何でもかまいません（詳細については、requests認証を参照）。

linkcheckビルダーは、linkcheck_auth リストで見つけることができる最初のマッチング auth_info 値を使用するため、リストの前にある値の方が優先度が高くなります。

例

linkcheck_auth = [
  ('https://foo\.yourcompany\.com/.+', ('johndoe', 'secret')),
  ('https://.+\.yourcompany\.com/.+', HTTPDigestAuth(...)),
]

バージョン 2.3 で追加。

linkcheck_allow_unauthorized
型:
bool
デフォルト:
False

WebサーバーがHTTP 401（認証されていない）応答を返した場合、linkcheckビルダーの現在のデフォルトの動作では、リンクを「破損」として扱います。この動作を変更するには、このオプションを True に設定します。

バージョン 8.0 で変更: このオプションのデフォルト値が False に変更されました。これは、チェックされたハイパーリンクへのHTTP 401応答がデフォルトで「破損」として扱われることを意味します。

バージョン 7.3 で追加。

linkcheck_rate_limit_timeout
型:
int
デフォルト:
300

linkcheck ビルダーは、短期間に同じサイトに多数のリクエストを発行する場合があります。この設定は、サーバーがリクエストがレート制限されていることを示す場合に、各試行間の最大待機時間（秒単位）を設定することにより、ビルダーの動作を制御します。これにより、失敗が記録されるまでの最大待機時間を設定します。

linkcheck ビルダーは常に、いつ再試行するかについてのサーバーの指示を尊重します（Retry-After ヘッダーを使用）。それ以外の場合、linkcheck は再試行するまで1分間待機し、成功するか、linkcheck_rate_limit_timeout （秒単位）を超えるまで、試行間の待機時間を2倍にし続けます。カスタムタイムアウトは、秒数を数値で指定する必要があります。

バージョン 3.4 で追加。

linkcheck_report_timeouts_as_broken
型:
bool
デフォルト:
False

ハイパーリンクからの応答を待っている間にlinkcheck_timeoutがタイムアウトした場合、linkcheckビルダーはデフォルトでリンクをtimeoutとして報告します。タイムアウトを代わりにbrokenとして報告するには、linkcheck_report_timeouts_as_brokenをTrueに設定します。

バージョン 8.0 で変更: このオプションのデフォルト値はFalseに変更されました。つまり、ハイパーリンクのチェック中に発生したタイムアウトは、新しい「timeout」ステータスコードを使用して報告されます。

バージョン 7.3 で追加。

linkcheck_request_headers
型:
dict[str, dict[str, str]]
デフォルト:
{}

URL（パスなし）をHTTPリクエストヘッダーにマッピングする辞書。

キーは'https://sphinx-doc.dokyumento.jp/'のようなURLベース文字列です。他のホストのヘッダーを指定するには、"*"を使用できます。URLが他の設定に一致しない場合にのみ、すべてのホストに一致します。

値は、ヘッダー名をその値にマッピングする辞書です。

例

linkcheck_request_headers = {
    "https://sphinx-doc.dokyumento.jp/": {
        "Accept": "text/html",
        "Accept-Encoding": "utf-8",
    },
    "*": {
        "Accept": "text/html,application/xhtml+xml",
    }
}

バージョン 3.1 で追加。

linkcheck_retries
型:
int
デフォルト:
1

linkcheckビルダーがURLを壊れていると宣言するまでに試行する回数。

バージョン 1.4 で追加。

linkcheck_timeout
型:
int
デフォルト:
30

linkcheckビルダーが各ハイパーリンクのリクエスト後に応答を待つ時間（秒単位）。

バージョン 1.1 で追加。

linkcheck_workers
型:
int
デフォルト:
5

リンクのチェック時に使用するワーカースレッドの数。

バージョン 1.1 で追加。

ドメインオプション

Cドメインのオプション

c_extra_keywords
型:
Set[str] | Sequence[str]
デフォルト:
['alignas', 'alignof', 'bool', 'complex', 'imaginary', 'noreturn', 'static_assert', 'thread_local']

Cパーサーによってキーワードとして認識される識別子のリスト。

バージョン 4.0.3 で追加.

バージョン 7.4 で変更: c_extra_keywordsがセットにできるようになりました。

c_id_attributes
型:
Sequence[str]
デフォルト:
()

パーサーが追加で属性として受け入れる必要がある文字列のシーケンス。たとえば、移植性のために、#defineが属性に使用されている場合に使用できます。

例

c_id_attributes = [
    'my_id_attribute',
]

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

バージョン 7.4 で変更: c_id_attributesがタプルにできるようになりました。

c_maximum_signature_line_length
型:
int | None
デフォルト:
None

シグネチャの文字数が設定された数を超えると、シグネチャ内の各パラメータが個別の論理行に表示されます。

None の場合、最大長はなく、シグネチャ全体が単一の論理行に表示されます。

これは、ドメイン固有の設定で、maximum_signature_line_lengthをオーバーライドします。

バージョン 7.1 で追加。

c_paren_attributes
型:
Sequence[str]
デフォルト:
()

パーサーが追加で1つの引数を持つ属性として受け入れる必要がある文字列のシーケンス。つまり、my_align_asがリストにある場合、my_align_as(X)は、括弧（()、[]、および{}）がバランスしているすべての文字列Xに対して属性として解析されます。たとえば、移植性のために、#defineが属性に使用されている場合に使用できます。

例

c_paren_attributes = [
    'my_align_as',
]

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

バージョン 7.4 で変更: c_paren_attributesがタプルにできるようになりました。

C++ドメインのオプション

cpp_id_attributes
型:
Sequence[str]
デフォルト:
()

パーサーが追加で属性として受け入れる必要がある文字列のシーケンス。たとえば、移植性のために、#defineが属性に使用されている場合に使用できます。

例

cpp_id_attributes = [
    'my_id_attribute',
]

バージョン 1.5 で追加。

バージョン 7.4 で変更: cpp_id_attributesがタプルにできるようになりました。

cpp_index_common_prefix
型:
Sequence[str]
デフォルト:
()

グローバルインデックスでC++オブジェクトをソートするときに無視されるプレフィックスのリスト。

例

cpp_index_common_prefix = [
    'awesome_lib::',
]

バージョン 1.5 で追加。

cpp_maximum_signature_line_length
型:
int | None
デフォルト:
None

シグネチャの文字数が設定された数を超えると、シグネチャ内の各パラメータが個別の論理行に表示されます。

None の場合、最大長はなく、シグネチャ全体が単一の論理行に表示されます。

これは、ドメイン固有の設定で、maximum_signature_line_lengthをオーバーライドします。

バージョン 7.1 で追加。

cpp_paren_attributes
型:
Sequence[str]
デフォルト:
()

パーサーが追加で1つの引数を持つ属性として受け入れる必要がある文字列のシーケンス。つまり、my_align_asがリストにある場合、my_align_as(X)は、括弧（()、[]、および{}）がバランスしているすべての文字列Xに対して属性として解析されます。たとえば、移植性のために、#defineが属性に使用されている場合に使用できます。

例

cpp_paren_attributes = [
    'my_align_as',
]

バージョン 1.5 で追加。

バージョン 7.4 で変更: cpp_paren_attributesがタプルにできるようになりました。

JavaScriptドメインのオプション

javascript_maximum_signature_line_length
型:
int | None
デフォルト:
None

シグネチャの文字数が設定された数を超えると、シグネチャ内の各パラメータが個別の論理行に表示されます。

None の場合、最大長はなく、シグネチャ全体が単一の論理行に表示されます。

これは、ドメイン固有の設定で、maximum_signature_line_lengthをオーバーライドします。

バージョン 7.1 で追加。

Pythonドメインのオプション

add_module_names
型:
bool
デフォルト:
True

モジュール名がすべてのオブジェクト名（ある種の「モジュール」が定義されているオブジェクトタイプの場合）の前に付加されるかどうかを決定するブール値。たとえば、py:functionディレクティブの場合。

modindex_common_prefix
型:
list[str]
デフォルト:
[]

Pythonモジュールインデックスをソートするために無視されるプレフィックスのリスト（たとえば、これが['foo.']に設定されている場合、foo.barはFではなくBの下に表示されます）。これは、単一のパッケージで構成されるプロジェクトをドキュメント化する場合に便利です。

注意

現在、HTMLビルダーでのみ機能します。

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

python_display_short_literal_types
型:
bool
デフォルト:
False

この値は、Literal型がどのように表示されるかを制御します。

例

以下の例では、次のpy:functionディレクティブを使用します

.. py:function:: serve_food(item: Literal["egg", "spam", "lobster thermidor"]) -> None

Falseの場合、Literal型は標準のPython構文に従って表示されます。つまり、

serve_food(item: Literal["egg", "spam", "lobster thermidor"]) -> None

Trueの場合、Literal型は、短く、PEP 604にインスパイアされた構文で表示されます。例えば、以下のようになります。

serve_food(item: "egg" | "spam" | "lobster thermidor") -> None

バージョン 6.2 で追加。

python_maximum_signature_line_length
型:
int | None
デフォルト:
None

シグネチャの文字数が設定された数を超えると、シグネチャ内の各パラメータが個別の論理行に表示されます。

None の場合、最大長はなく、シグネチャ全体が単一の論理行に表示されます。

これは、ドメイン固有の設定で、maximum_signature_line_lengthをオーバーライドします。

Pythonドメインの場合、シグネチャの長さは、型パラメータまたは引数リストのどちらをフォーマットしているかによって異なります。前者では、シグネチャの長さは引数リストの長さを無視し、後者では、シグネチャの長さは型パラメータリストの長さを無視します。

例えば、python_maximum_signature_line_length = 20 の場合、型パラメータのリストのみが折り返され、引数リストは1行でレンダリングされます。

.. py:function:: add[T: VERY_LONG_SUPER_TYPE, U: VERY_LONG_SUPER_TYPE](a: T, b: U)

バージョン 7.1 で追加。

python_use_unqualified_type_names
型:
bool
デフォルト:
False

解決可能な場合は、Python参照のモジュール名を抑制します。

バージョン 4.0 で追加。

注意

この機能は実験的なものです。

trim_doctest_flags
型:
bool
デフォルト:
True

インタラクティブなPythonセッション（つまり、doctest）を表示するすべてのコードブロックについて、行末にあるdoctestフラグ（# doctest: FLAG, ...のようなコメント）と<BLANKLINE>マーカーを削除します。doctestを含める方法の詳細については、拡張機能doctestを参照してください。

バージョン 1.0 で追加。

バージョン 1.1 で変更: <BLANKLINE>も削除するようになりました。

拡張機能のオプション

拡張機能には、独自の構成オプションが頻繁にあります。Sphinxのファーストパーティ拡張機能のオプションについては、各拡張機能のページで説明されています。

設定ファイルの例

# -- Project information -----------------------------------------------------
# https://sphinx-doc.dokyumento.jp/en/master/usage/configuration.html#project-information

project = 'Test Project'
copyright = '2000-2042, The Test Project Authors'
author = 'The Authors'
version = release = '4.16'

# -- General configuration ------------------------------------------------
# https://sphinx-doc.dokyumento.jp/en/master/usage/configuration.html#general-configuration

exclude_patterns = [
    '_build',
    'Thumbs.db',
    '.DS_Store',
]
extensions = []
language = 'en'
master_doc = 'index'
pygments_style = 'sphinx'
source_suffix = '.rst'
templates_path = ['_templates']

# -- Options for HTML output ----------------------------------------------
# https://sphinx-doc.dokyumento.jp/en/master/usage/configuration.html#options-for-html-output

html_theme = 'alabaster'
html_static_path = ['_static']