LaTeX のカスタマイズ

HTML ビルダー と異なり、 latex ビルダーには用意されたテーマの利点がありません。LaTeX 出力オプション、特に latex_elements 変数が、カスタマイズのためのインターフェースの多くを提供します。例えば

# inside conf.py
latex_engine = 'xelatex'
latex_elements = {
    'passoptionstopackages': r'''
\PassOptionsToPackage{svgnames}{xcolor}
''',
    'fontpkg': r'''
\setmainfont{DejaVu Serif}
\setsansfont{DejaVu Sans}
\setmonofont{DejaVu Sans Mono}
''',
    'preamble': r'''
\usepackage[titles]{tocloft}
\cftsetpnumwidth {1.25cm}\cftsetrmarg{1.5cm}
\setlength{\cftchapnumwidth}{0.75cm}
\setlength{\cftsecindent}{\cftchapnumwidth}
\setlength{\cftsecnumwidth}{1.25cm}
''',
    'sphinxsetup': 'TitleColor=DarkGoldenrod',
    'fncychap': r'\usepackage[Bjornstrup]{fncychap}',
    'printindex': r'\footnotesize\raggedright\printindex',
}
latex_show_urls = 'footnote'

注釈

バックスラッシュは、エスケープシーケンスとして解釈されるのを避けるために、Python の文字列リテラルでは2重にする必要があることに注意してください。または、上記のように raw 文字列を使用することもできます。

latex_elements 設定

通常、Sphinx が生成された .tex ファイルに記述する LaTeX スニペットを上書きする辞書です。その 'sphinxsetup' キーについては別途説明します。また、raw ディレクティブを介して、生成されたファイルにローカル構成を挿入することもできます。例えば、PDF ドキュメントでは、この章は後述するように特別にスタイル設定されています。

上書きしたいキーには以下のようなものがあります。

'papersize'

ドキュメントクラスの用紙サイズオプション ('a4paper' または 'letterpaper')

デフォルト: 'letterpaper'

'pointsize'

ドキュメントクラスのポイントサイズオプション ('10pt', '11pt' または '12pt')

デフォルト: '10pt'

'pxunit'

画像の属性 width および height で使用されるときの px の値。デフォルト値は '0.75bp' で、96px=1in になります (TeX では 1in = 72bp = 72.27pt)。たとえば、100px=1in を得るには、'0.01in' または '0.7227pt' を使用します (後者は、仕様で使用されている単位が小さいため、TeX がより正確な値を計算するようになります)。72px=1in の場合は、単に '1bp' を使用します。90px=1in の場合は、'0.8bp' または '0.803pt' を使用します。

デフォルト: '0.75bp'

バージョン 1.5 で追加。

'passoptionstopackages'

プリアンブルの早い段階に配置される文字列で、\PassOptionsToPackage{options}{foo} コマンドを含めるように設計されています。

ヒント

これはプリアンブルの非常に早い段階で LaTeX パッケージをロードするためにも使用できます。たとえば、パッケージ fancybox は 'preamble' キーでロードすると互換性がなく、より早くロードする必要があります。

デフォルト: ''

バージョン 1.4 で追加。

'babel'

“babel” パッケージのインクルージョン、デフォルト r'\usepackage{babel}' (適切なドキュメント言語文字列がクラスオプションとして渡され、言語がない場合は english が使用されます)。日本語のドキュメントの場合、デフォルトは空の文字列です。

XeLaTeX および LuaLaTeX を使用すると、Sphinx は LaTeX ドキュメントが polyglossia を使用するように構成しますが、現在の babel は近年 Unicode エンジンのサポートを改善しており、一部の言語では polyglossia よりも babel を優先することが理にかなっている可能性があることに注意してください。

ヒント

このコア LaTeX キーのようなものを変更した後は、次の PDF ビルドの前に LaTeX ビルド リポジトリをクリーンアップしてください。そうしないと、残りの補助ファイルがビルドを壊す可能性があります。

デフォルト: r'\usepackage{babel}' (日本語ドキュメントの場合)

バージョン 1.5 で変更: latex_engine が 'xelatex' に設定されている場合、デフォルトは '\\usepackage{polyglossia}\n\\setmainlanguage{<language>}' です。

バージョン 1.6 で変更: 'lualatex' は 'xelatex' と同じデフォルト設定を使用します

バージョン 1.7.6 で変更: 'xelatex' ('lualatex' ではない) を使用するフランス語の場合、デフォルトは polyglossia ではなく babel を使用することです。

バージョン 7.4.0 で変更: 'lualatex' を使用するフランス語の場合、デフォルトは babel を使用することです。

'fontpkg'

フォントパッケージのインクルージョン。'pdflatex' でのデフォルトは

r"""\usepackage{tgtermes}
\usepackage{tgheros}
\renewcommand\ttdefault{txtt}
"""

一方、'xelatex' および 'lualatex' の場合、LaTeX パッケージ fontspec ( 'fontenc' 経由で含まれる) の \setmainfont、\setsansfont および \setmonofont コマンドを使用して、GNU FreeSerif、FreeSans、および FreeMono の OpenType フォントをドキュメント フォントとして設定します (比率 0.9 でスケーリングされます)。

バージョン 1.2 で変更: language がキリル文字を使用する場合、デフォルトは '' です。

バージョン 2.0 で変更: 'pdflatex' エンジンを使用するドキュメントで、時折ギリシャ語またはキリル文字をサポートするのに役立つフォント置換コマンドが組み込まれています。4.0.0 では、これらのコマンドは 'fontsubstitution' キーに移動されました。

バージョン 4.0.0 で変更: デフォルトのフォント設定が変更されました。上記のように、セリフとサンセリフには Times と Helvetica のクローンを使用していますが、より優れた、より完全な TeX フォントと関連する LaTeX パッケージを使用しています。モノスペース フォントは、Times クローンによく合うように変更されました。

バージョン 8.1.0 で変更: Unicode エンジンで使用されるモノスペース フォント FreeMono は、スケール 0.9 でロードされます。これは、\small を使用するようにコードブロックを構成した 'fvset' による以前のメカニズムを置き換えます。インライン リテラルは、周囲のテキストによく適合するようになり、'fvset' はデフォルトでは介入しなくなるため、カスタム フォントを設定するのが簡単になります。

'fncychap'

“fncychap” パッケージ (おしゃれな章タイトルを作成する) のインクルージョン、英語ドキュメントのデフォルトは r'\usepackage[Bjarne]{fncychap}' (このオプションは Sphinx によってわずかにカスタマイズされています)、国際化されたドキュメントの場合は r'\usepackage[Sonny]{fncychap}' (“Bjarne” スタイルは英語で綴られた数字を使用するため)。試せるその他の “fncychap” スタイルは “Lenny”、“Glenn”、“Conny”、“Rejne”、および “Bjornstrup” です。これを '' に設定して、fncychap を無効にすることもできます。

デフォルト: 英語ドキュメントの場合は r'\usepackage[Bjarne]{fncychap}'、国際化されたドキュメントの場合は r'\usepackage[Sonny]{fncychap}'、日本語ドキュメントの場合は '' です。

'preamble'

追加の前文コンテンツです。必要なマクロをすべてプロジェクトのソースリポジトリのmystyle.tex.txtのようなファイルに移動し、LaTeX が実行時にそれをインポートするように設定できます。

'preamble': r'\input{mystyle.tex.txt}',
# or, if the \ProvidesPackage LaTeX macro is used in a file mystyle.sty
'preamble': r'\usepackage{mystyle}',

その場合、latex_additional_filesを適切に設定する必要があります。例えば、次のようになります。

latex_additional_files = ["mystyle.sty"]

.texをサフィックスとして使用しないでください。そうしないと、ファイル自体が PDF ビルドプロセスに送信されてしまいます。上記の例のように、.tex.txtまたは.styを使用してください。

デフォルト: ''

'figure_align'

LaTeX の図のフロート配置。画像が現在のページに収まらない場合は、次のページに「フロート」されますが、その前に他のテキストを置くことができます。この動作が気に入らない場合は、「H」を使用してください。これによりフロートが無効になり、図がソースに表示される順序で厳密に配置されます。

デフォルト: 'htbp' (ここ、上、下、ページ)

バージョン 1.3 で追加。

'atendofbody'

追加のドキュメントコンテンツ（インデックスの直前）。

デフォルト: ''

バージョン 1.5 で追加。

'extrapackages'

追加の LaTeX パッケージ。例:

latex_elements = {
    'extrapackages': r'\usepackage{isodate}'
}

指定された LaTeX パッケージは、hyperref パッケージと Sphinx 拡張機能からロードされたパッケージの前にロードされます。

ヒント

hyperref の後に LaTeX パッケージを追加でロードする場合は、代わりに'preamble'キーを使用してください。

デフォルト: ''

バージョン 2.3 で追加。

'footer'

追加のフッターコンテンツ（インデックスの前）。

デフォルト: ''

バージョン 1.5 で非推奨: 代わりに'atendofbody'キーを使用してください。

特別な場合を除き、オーバーライドする必要がないキーは次のとおりです。

'extraclassoptions'

デフォルトは空の文字列です。例:'extraclassoptions': 'openany'を設定すると、章（'manual'タイプのドキュメントの場合）を任意のページから開始できます。

デフォルト: ''

バージョン 1.2 で追加。

バージョン 1.6 で変更: このドキュメントを追加。

'maxlistdepth'

LaTeX では、デフォルトで最大 6 レベルのリストと引用のような環境のネストが許可されており、最大 4 つの番号付きリストと 4 つの箇条書きリストが可能です。このキーを例えば'10'（文字列として）に設定すると、最大 10 レベルのネスト（すべての種類）が可能になります。空の文字列のままにすると、LaTeX のデフォルトに従うことを意味します。

警告

• このキーを使用すると、一部の LaTeX パッケージや独自のリストカスタマイズを行う特別なドキュメントクラスと互換性がない場合があります。

• ドキュメントプリアンブル内で\usepackage{enumitem}が実行された場合、キー設定は無視されます。この LaTeX パッケージの専用コマンドを使用してください。

デフォルト: 6

バージョン 1.5 で追加。

'inputenc'

“inputenc” パッケージのインクルード。

デフォルト: pdflatex を使用する場合はr'\usepackage[utf8]{inputenc}'、それ以外の場合は''。

注釈

utf8の代わりにutf8xを使用する場合は、LaTeX プリアンブルを適切な\PreloadUnicodePage{<number>}コマンドで拡張する必要があります。utf8xのドキュメント（TeXLive ベースの TeX インストールではtexdoc ucs）を参照してください。そうしないと、特にハイパーリンクに関して、PDF で予期しない、そして見つけにくい問題（ビルドクラッシュを引き起こさない）が発生する可能性があります。

これらの予防措置を講じた場合でも、pdflatexエンジンを介した PDF ビルドは、アップストリームの LaTeX がutf8xと完全に互換性がないためにクラッシュする可能性があります。たとえば、コードブロックに関連する場合や、ファイル名に Unicode 文字が含まれている画像をインクルードしようとする場合などです。実際、2015 年以降、pdflatexエンジンを備えたアップストリームの LaTeX は Unicode のネイティブサポートをある程度強化しており、utf8xとの互換性がますます低下しています。特に、2019 年 10 月の LaTeX リリース以降、ファイル名で Unicode 文字やスペースを使用できます。Sphinx レベルでは、たとえば、imageおよびfigureディレクティブが、LaTeX 出力を介した PDF でそのようなファイル名と互換性があることを意味します。ただし、utf8xを使用している場合は壊れています。

バージョン 1.4.3 で変更: 以前は、すべてのコンパイラでr'\usepackage[utf8]{inputenc}'が使用されていました。

'cmappkg'

“cmap” パッケージのインクルード。

デフォルト: r'\usepackage{cmap}'

バージョン 1.2 で追加。

'fontenc'

latex_engineとして'pdflatex'の場合のデフォルトは、r'\usepackage[T1]{fontenc}'です。（'pdflatex'を使用している場合）次のように置き換えます。

• r'\usepackage[X2,T1]{fontenc}'時折キリル文字が必要な場合（физика частиц）、

• r'\usepackage[LGR,T1]{fontenc}'時折ギリシャ文字が必要な場合（Σωματιδιακή φυσική）、

• r'\usepackage[LGR,X2,T1]{fontenc}'両方が必要な場合。

TeX インストールには、追加のパッケージが必要な場合があります。例えば、Ubuntu xenial では

• ギリシャ語（LGR）にはtexlive-lang-greekとcm-superが必要です。

• キリル文字（X2）にはtexlive-lang-cyrillicとcm-superが必要です。

'xelatex'と'lualatex'を使用すると、ギリシャ語とキリル文字のサポートはすぐに使用できます。この'fontenc'キーは、LaTeX パッケージfontspec（以下に説明するいくつかの追加機能を含む）を含めることをデフォルトとし、本文フォントとして GNU FreeSerif フォントを選択します。'fontpkg'を参照してください。

バージョン 1.5 で変更: latex_engineが'xelatex'に設定されている場合は、r'\usepackage{fontspec}'がデフォルトです。

バージョン 1.6 で変更: latex_engineが'lualatex'に設定されている場合は、r'\usepackage{fontspec}'がデフォルトです。

バージョン 2.0 で変更: 'lualatex'は、<<と>>の TeX 合字を無効にするために、追加で\defaultfontfeatures[\rmfamily,\sffamily]{}を実行します。

バージョン 2.0 で変更: LGR、T2A、またはX2がこのキーで検出された場合、'pdflatex'で時折ギリシャ語またはキリル文字をサポートするために、追加の LaTeX 設定が自動的に実行されます。

バージョン 2.2.1 で変更: メイン言語がギリシャ語であるドキュメントは、デフォルトで'xelatex'になり、'fontenc'キーを設定しないでください。これによりfontspecがロードされます。

バージョン 2.3.0 で変更: 'xelatex'は、--をエンダッシュに縮約することを回避し、ストレートクォートをカーリークォートに変換しないように\defaultfontfeatures[\rmfamily,\sffamily]{}を実行します（それ以外の場合、smartquotesがFalseに設定されている場合でも発生します）。

'fontsubstitution'

'fontenc' が LGR または X2 (または T2A) を使用するように設定されていない場合は無視されます。'fontpkg' キーが LGR または X2 エンコーディングで利用可能であることがわかっている一部の TeX フォントで使用するように設定されている場合は、これを空の文字列に設定します。それ以外の場合はデフォルトのままにします。

latex_engine が 'pdflatex' 以外の場合は無視されます。

バージョン 4.0.0 で追加。

'textgreek'

時折使用するギリシャ文字のサポート用。

latex_engine が 'platex', 'xelatex', 'lualatex' の場合は無視され、'pdflatex' の場合は、'fontenc' キーが LGR と共に使用されたかどうかによって、空の文字列または r'\usepackage{textalpha}' のいずれかがデフォルトとなります。このキーをカスタマイズしたいのは、LaTeX のエキスパートユーザーのみでしょう。

r'\usepackage{textalpha,alphabeta}' として使用して、math コンテキストで 'pdflatex' がギリシャ語 Unicode 入力をサポートするようにすることもできます。たとえば、:math:`α` (U+03B1) は \(\alpha\) としてレンダリングされます。

デフォルト: r'\usepackage{textalpha}' または fontenc が LGR オプションを含まない場合は ''。

バージョン 2.0 で追加。

'geometry'

“geometry” パッケージのインクルージョン。デフォルトは、日本語文書の場合は r'\usepackage{geometry}' または r'\usepackage[dvipdfm]{geometry}'。 Sphinx LaTeX スタイルファイルは追加で実行します。

\PassOptionsToPackage{hmargin=1in,vmargin=1in,marginpar=0.5in}{geometry}

これは、対応する ‘sphinxsetup’ オプション を介してカスタマイズできます。

バージョン 1.5 で追加。

バージョン 1.5.2 で変更: latex_engine が 'platex' の場合は dvipdfm オプション。

バージョン 1.5.3 で追加: マージン用の ‘sphinxsetup’ キー。

バージョン 1.5.3 で変更: LaTeX ファイル内の場所が、\usepackage{sphinx} および \sphinxsetup{..} の後、つまり、'fontpkg' キーの挿入後に移動されました。これは、日本語文書の紙面レイアウトオプションを特別な方法で処理するためです。テキスト幅は *全角* 幅の整数倍に設定され、テキストの高さはベースラインの整数倍に設定されます。詳しくは、hmargin のドキュメントを参照してください。

'hyperref'

“hyperref” パッケージのインクルージョン。さらにパッケージ “hypcap” をロードし、\urlstyle{same} を発行します。これは、sphinx.sty ファイルがロードされた後、'preamble' キーの内容が実行される前に行われます。

注意

パッケージ “hyperref” および “hypcap” のロードは必須です。

バージョン 1.5 で追加: 以前は、これは sphinx.sty の内部から実行されていました。

'maketitle'

“maketitle” の呼び出し。別のスタイルでタイトルページを生成したい場合は上書きしてください。

ヒント

キーの値が r'\newcommandsphinxbackoftitlepage{<Extra material>}\sphinxmaketitle' に設定されている場合、<Extra material> は、タイトルページの裏面 (docclass が 'manual' の場合のみ) に組版されます。

デフォルト: r'\sphinxmaketitle'

バージョン 1.8.3 で変更: ドキュメントクラスのオリジナルの \maketitle は上書きされないため、このキーのカスタム設定の一部として再利用できます。

バージョン 1.8.3 で追加: \sphinxbackoftitlepage オプションのマクロ。これは、このキーではなく 'preamble' キー内でも定義できます。

'releasename'

タイトルページの 'release' 要素に接頭辞を付ける値。latex_documents のタプルで使用される *title* および *author* と同様に、LaTeX マークアップとして挿入されます。

デフォルト: 'Release'

'tableofcontents'

“tableofcontents” の呼び出し。デフォルトの r'\sphinxtableofcontents' は、変更されていない \tableofcontents のラッパーであり、ユーザーがロードしたパッケージでカスタマイズできます。別の目次を生成したり、タイトルページと目次の間にコンテンツを配置したりする場合は上書きしてください。

デフォルト: r'\sphinxtableofcontents'

バージョン 1.5 で変更: 以前は、\tableofcontents 自体の意味が Sphinx によって変更されていました。これにより、“tocloft” や “etoc” などの変更を行う専用パッケージとの間に非互換性が生じていました。

'transition'

トランジションを表示するために使用されるコマンド。トランジションを別の方法で表示したい場合は上書きしてください。

デフォルト: '\n\n\\bigskip\\hrule\\bigskip\n\n'

バージョン 1.2 で追加。

バージョン 1.6 で変更: 以前は \hrule の後にあった不要な {} を削除しました。

'makeindex'

“makeindex” の呼び出し。 \begin{document} の直前の最後に行います。r'\usepackage[columns=1]{idxlayout}\makeindex' を指定すると、インデックスは 1 つの列のみを使用します。idxlayout LaTeX パッケージをインストールする必要がある場合があります。

デフォルト: r'\makeindex'

'printindex'

“printindex” の呼び出し。ファイルの最後に行います。インデックスを別の方法で生成したり、インデックスの後にコンテンツを追加したり、フォントを変更したりする場合は上書きしてください。LaTeX はインデックスに 2 列モードを使用するため、このキーを r'\footnotesize\raggedright\printindex' に設定することをお勧めします。または、1 列のインデックスを取得するには、r'\def\twocolumn[#1]{#1}\printindex' を使用します (カスタムドキュメントクラスを使用している場合、このトリックが失敗する可能性があります。その場合は、'makeindex' キーのドキュメントで説明されている idxlayout のアプローチを試してください)。

デフォルト: r'\printindex'

'fvset'

fancyvrb LaTeX パッケージのカスタマイズ。

デフォルト値は r'\fvset{fontsize=auto}' です。これは、コードブロックが脚注で終わる場合にフォントサイズが正しく調整されることを意味します。カスタム等幅フォントを使用する場合はこれを変更する必要がある場合があります。たとえば、Courier のようなフォントの場合は r'\fvset{fontsize=\small}' に設定します (Unicode エンジンでは、fontspec の \setmonofont LaTeX コマンドの Scale インターフェイスを使用することをお勧めします)。

デフォルト: r'\fvset{fontsize=auto}'

バージョン 1.8 で追加。

バージョン 2.0 で変更: 'xelatex' および 'lualatex' の場合、FreeFont ファミリーの相対的な幅に適合するため、デフォルトは r'\fvset{fontsize=\small}' になります。

バージョン 4.0.0 で変更: 'pdflatex' のデフォルト値が変更されました。以前は r'\fvset{fontsize=\small}' を使用していました。

バージョン 4.1.0 で変更: 中国語ドキュメントのデフォルト値が r'\fvset{fontsize=\small,formatcom=\xeCJKVerbAddon}' に変更されました。

バージョン 8.1.0 で変更: 'xelatex' および 'lualatex' のデフォルト値も r'\fvset{fontsize=auto}' に変更されました。デフォルトの等幅フォント FreeMono のリスケーリングは、LaTeX パッケージ fontspec インターフェースを介して設定されるようになりました。 'fontpkg' を参照してください。

他のオプションで設定されているため、上書きすべきではないキーは次のとおりです。

'docclass' 'classoptions' 'title' 'release' 'author'

sphinxsetup 設定

バージョン 1.5 で追加。

latex_elements の 'sphinxsetup' キーは、LaTeX タイプのカスタマイズインターフェースを提供します。

latex_elements = {
    'sphinxsetup': 'key1=value1, key2=value2, ...',
}

ブール値キーの LaTeX 構文では、小文字の true または false が必要です。例えば、'sphinxsetup': "verbatimwrapslines=false" のように記述します。ブール値キーを true に設定する場合、=true はオプションです。コンマと等号の前後のスペースは無視されますが、LaTeX マクロ内のスペースは意味がある場合があります。文字列または数値の値を囲むために、バッククォートや引用符を使用しないでください。

'sphinxsetup' はデフォルトで空です。空でない場合、ドキュメントのプリアンブル内の \sphinxsetup マクロへの引数として次のように渡されます。

\usepackage{sphinx}
\sphinxsetup{key1=value1, key2=value2,...}

\sphinxsetup LaTeX マクロの使用を、raw ディレクティブを介して、ドキュメントの本文に直接挿入することができます。

.. raw:: latex

   \begingroup
   \sphinxsetup{%
      TitleColor=DarkGoldenrod,
      ... more comma separated key=value using LaTeX syntax ...
   }

All elements here will be under the influence of the raw ``\sphinxsetup``
settings.

.. raw:: latex

   \endgroup

From here on, the raw ``\sphinxsetup`` has no effect anymore.

これは、特に PDF 出力に関するドキュメントのこの部分をスタイル設定するために使用されてきた手法です。実際に使用されているオプションは、開発リポジトリの doc/latex.rst の上部にあります。

上記の例で使用されている色は、"xcolor" パッケージに svgnames オプションを渡すことで利用可能になります。

latex_elements = {
    'passoptionstopackages': r'\PassOptionsToPackage{svgnames}{xcolor}',
}

bookmarksdepth

PDF の折りたたみ可能なブックマークパネルの深さを制御します。数値（例：3）または LaTeX のセクション名（例：subsubsection、つまりバックスラッシュなし）のいずれかを使用できます。詳細については、hyperref LaTeX ドキュメントを参照してください。

デフォルト: 5

バージョン 4.0.0 で追加。

hmargin, vmargin

水平（または垂直）マージンの寸法。 geometry パッケージに hmargin （または vmargin）オプションとして渡されます。例:

'sphinxsetup': 'hmargin={2in,1.5in}, vmargin={1.5in,2in}, marginpar=1in',

現在、日本語ドキュメントでは、これらのパラメーターに対して一次元の形式のみを受け入れます。次に、geometry パッケージには、テキスト幅が *全角* 幅の正確な倍数になるように、またテキストの高さが baselineskip の整数倍になるように、マージンに最も近いフィットで適切なオプションが渡されます。

デフォルト: 1in ({1in,1in} と同等)

ヒント

ポイントサイズが 11pt または 12pt の日本語の 'manual' docclass では、nomag の追加ドキュメントクラスオプションを使用します（latex_elements の 'extraclassoptions' キーを参照）または、いわゆる TeX の「true」単位を使用します。

'sphinxsetup': 'hmargin=1.5truein, vmargin=1.5truein, marginpar=5zw',

バージョン 1.5.3 で追加。

marginpar

\marginparwidth LaTeX ディメンション。日本語ドキュメントの場合、値は *全角* 幅の最も近い整数倍になるように変更されます。

デフォルト: 0.5in

バージョン 1.5.3 で追加。

mathnumsep

これは、math_numsep (それ自体がデフォルトで '.') によって設定された文字列（引用符なし！）をデフォルトとします。LaTeX 出力に異なる設定が必要な場合に使用します。

バージョン 8.1.0 で追加。

verbatimwithframe

code-block とリテラルインクルードをフレームで囲むかどうかを指定するブール値。 false に設定しても、オプションの背景色で使用されているため、パッケージ “framed” の使用は無効になりません。

デフォルト: true。

verbatimwrapslines

code-block の内容の長い行を折り返すかどうかを指定するブール値。

true の場合、改行はスペース（改行前の最後のスペースは特別な記号を使用してレンダリングされます）および ASCII 句読点文字（つまり、文字や数字ではない）で発生する可能性があります。長い文字列に改行ポイントがない場合は、次の行に移動されます。その長さが行の幅より長い場合は、オーバーフローします。

デフォルト: true

verbatimforcewraps

code-block の内容の長い行を、長い文字列が原因でオーバーフローしないように強制的に折り返すかどうかを指定するブール値。

注釈

Pygments LaTeXFormatter が、追加の（任意）LaTeX マークアップを許可する texcomments または類似のオプションとともに使用されていないことが前提となります。

また、latex_engine が 'pdflatex' に設定されている場合は、Unicode コードポイントのデフォルトの LaTeX 処理、つまり utf8 であり utf8x ではないものが許可されます。

デフォルト: false

バージョン 3.5.0 で追加。

verbatimmaxoverfull

数値。分割不可能な長い文字列の長さが、合計行幅にこの文字数を加えた値よりも大きい場合、および verbatimforcewraps モードがオンの場合、入力行は各文字にブレークポイントを適用する強制的なアルゴリズムを使用してリセットされます。

デフォルト: 3

バージョン 3.5.0 で追加。

verbatimmaxunderfull

verbatimforcewraps モードが適用され、スペースと句読点での行折り返しを適用した後、分割された行の最初の部分が利用可能な幅を埋めるために少なくともその文字数が不足している場合、入力行は強制的なアルゴリズムを使用してリセットされます。

デフォルトが高く設定されているため、強制的なアルゴリズムはオーバーフルの場合、つまり完全な行幅よりも長い文字列が存在する場合にのみトリガーされます。これを 0 に設定すると、すべての入力行が現在利用可能な行幅でハード折り返しされるようになります。

latex_elements = {
    'sphinxsetup': "verbatimforcewraps, verbatimmaxunderfull=0",
}

これは、raw latex ディレクティブを使用して、適切な \sphinxsetup を（前後に）latex ファイルに挿入することで、特定のコードブロックに対してローカルに実行できます。

デフォルト: 100

バージョン 3.5.0 で追加。

verbatimhintsturnover

コードブロックに改ページが発生した場合、「次のページに続く」と「前のページから続く」のヒントを表示するかどうかを指定するブール値。

デフォルト: true

バージョン 1.6.3 で追加。

バージョン 1.7 で変更: デフォルトが false から true に変更されました。

verbatimcontinuedalign, verbatimcontinuesalign

フレームで囲まれた内容に対する水平位置: l (左揃え)、r (右揃え)、または c (中央揃え) のいずれか。

デフォルト: r

バージョン 1.7 で追加。

parsedliteralwraps

parsed-literal の内容の長い行を折り返す必要があるかどうかを指定するブール値。

デフォルト: true

バージョン 1.5.2 で追加: 以前の動作を復元するには、このオプション値を false に設定します。

inlineliteralwraps

インラインリテラル内での改行を許可するかどうかを指定するブール値: ただし、追加の潜在的な改行ポイント（スペースまたはハイフネーションによって LaTeX で許可されているものに加えて）は、現在、文字 . , ; ? ! / と \ の後にのみ挿入されます。TeX の内部構造のため、行内の空白は、改行に対応するために引き伸ばされる（または縮小される）ます。

デフォルト: true

バージョン 1.5 で追加: 以前の動作を復元するには、このオプション値を false に設定します。

バージョン 2.3.0 で変更: \ 文字に潜在的な改行ポイントが追加されました。

verbatimvisiblespace

長いコード行が分割されたとき、改行位置の直前のソースコード行からの最後のスペース文字は、これを使用してタイプセットされます。

デフォルト: \textcolor{red}{\textvisiblespace}

verbatimcontinued

継続コード行の先頭に挿入される LaTeX マクロ。（複雑な…）デフォルトでは、右を指す小さな赤いフックがタイプセットされます。

\makebox[2\fontcharwd\font`\x][r]{\textcolor{red}{\tiny$\hookrightarrow$}}

バージョン 1.5 で変更: 長いコード行の折り返しは 1.4.2 で追加されました。継続記号のデフォルト定義は、様々なフォントサイズ（例：脚注内のコードブロック）に対応するために 1.5 で変更されました。

注釈

カラーキーの値は、以下のいずれかの構文に従う必要があります。

• \definecolor LaTeX コマンドの構文に従うもの。例えば、VerbatimColor={rgb}{0.2,0.3,0.5} や {RGB}{37,23,255} や {gray}{0.75} や {HTML}{808080} など。

• または、xcolor パッケージの \colorlet コマンドの構文に従うもの。例えば、VerbatimColor=red!10 や red!50!green や -red!75 や MyPreviouslyDefinedColor など。この構文については xcolor のドキュメントを参照してください。

バージョン 5.3.0 で変更: 以前は \definecolor 構文のみが受け入れられていました。

TitleColor

タイトル（パッケージ "titlesec" を使用して設定されたもの）の色。

デフォルト: {rgb}{0.126,0.263,0.361}

InnerLinkColor

hyperref に linkcolor および citecolor の値として渡される色。

デフォルト: {rgb}{0.208,0.374,0.486}。

OuterLinkColor

hyperref に filecolor, menucolor, および urlcolor の値として渡される色。

デフォルト: {rgb}{0.216,0.439,0.388}

VerbatimColor

code-block の背景色。

デフォルト: {RGB}{242,242,242} （{gray}{0.95} と同じ）。

バージョン 6.0.0 で変更: 以前は {rgb}{1,1,1} (白) でした。

VerbatimBorderColor

フレームの色。

デフォルト: {RGB}{32,32,32}

バージョン 6.0.0 で変更: 以前は {rgb}{0,0,0} (黒) でした。

VerbatimHighlightColor

強調表示された行の色。

デフォルト: {rgb}{0.878,1,1}

バージョン 1.6.6 で追加。

TableRowColorHeader

テーブルのヘッダー行（すべて）の背景色を設定します。

latex_table_style に 'colorrows' が含まれているか、テーブルに colorrows クラスが割り当てられている場合にのみ有効になります。nocolorrows クラスを持つテーブルでは無視されます。

他の 'sphinxsetup' キーと同様に、raw ディレクティブを介して挿入された \sphinxsetup{...} LaTeX コマンドから、または コンテナクラス に関連付けられた LaTeX 環境から \sphinxsetup{...} を使用して設定または変更することもできます。

デフォルト: {gray}{0.86}

TableMergeColorHeader もあります。使用すると、ヘッダー内の結合された単一行セルに特定の色を設定します。

バージョン 5.3.0 で追加。

TableRowColorOdd

テーブルの奇数行の背景色を設定します（行数は、最初のヘッダーではない行で 1 から開始されます）。latex_table_style に 'colorrows' が含まれているか、colorrows クラスが割り当てられた特定のテーブルでのみ有効です。

デフォルト: {gray}{0.92}

TableMergeColorOdd もあります。

バージョン 5.3.0 で追加。

TableRowColorEven

テーブルの偶数行の背景色を設定します。

デフォルト {gray}{0.98}

TableMergeColorEven もあります。

バージョン 5.3.0 で追加。

verbatimsep

コード行とフレームの間の間隔。

エイリアス pre_padding および追加のキーについては、追加の CSS ライクな 'sphinxsetup' キー を参照してください。

デフォルト: \fboxsep

verbatimborder

code-block の周囲のフレームの幅。pre_border-width については、追加の CSS ライクな 'sphinxsetup' キー も参照してください。

デフォルト: \fboxrule

重要

8.1.0 以降、topic, contents, および sidebar ディレクティブを個別にスタイル設定できるようになり、デフォルトが異なります。追加の CSS ライクな 'sphinxsetup' キー を参照してください。次の 3 つのキーは、3 つのディレクティブを区別しないレガシーインターフェースとして保持されています。

shadowsep

このレガシーオプションは、topic, contents, および sidebar ディレクティブのパディング（すべての方向で同じ）を同時に設定します。

shadowsize

このレガシーオプションは、topic, contents, および sidebar ディレクティブの影の幅を同時に設定します。

shadowrule

このレガシーオプションは、topic, contents, および sidebar ディレクティブの境界線の幅（すべての辺で同じ）を同時に設定します。

重要

7.4.0 では、すべてのアドモニション（danger 型だけでなく）が、5.1.0 および 6.2.0 で追加された機能を使用します。すべてのデフォルトが変更されました。

iconpackage

アドモニションタイトルのアイコンに使用される LaTeX パッケージの名前。デフォルトは fontawesome5 またはフォールバック fontawesome です。どちらも利用できない場合、オプション値は自動的に none にデフォルト設定されます。これは、パッケージのロードを試みないことを意味します。この設定とは無関係に、追加の CSS ライクな 'sphinxsetup' キー セクションで説明されている div.<type>_icon-title キーを介して、任意のアドモニションタイプに任意の LaTeX コードを関連付けることができます。これらのキーを使用しない場合、Sphinx はアイコンのデフォルトの選択を適用するか（fontawesome{5,} が利用可能な場合）、アイコンをまったく描画しません。フォールバック fontawesome が使用される場合、caution および danger の共通アイコンは、fontawesome5 でのみ見られる「放射能」ではなく、デフォルトで「ボルト」になります。

バージョン 7.4.0 で追加。

noteBorderColor, hintBorderColor, importantBorderColor, tipBorderColor

アドモニションの境界線の色。

デフォルト: {RGB}{134,152,155}。

バージョン 7.4.0 で変更。

noteBgColor, hintBgColor, importantBgColor, tipBgColor

アドモニションの背景色。

デフォルト: {RGB}{247,247,247}。

バージョン 6.2.0 で追加。

バージョン 7.4.0 で変更。

noteTextColor, hintTextColor, importantTextColor, tipTextColor

アドモニションの内容の色。

デフォルト: 設定なし（内容テキストは周囲のテキスト色を使用します。原則として黒）

バージョン 6.2.0 で追加: 7.0.0 まで実験的なものと見なされます。これらのオプションには、追加の CSS ライクな 'sphinxsetup' キー で説明されている div.note_TeXcolor (など) というエイリアスがあります。後者を使用すると、Sphinx は 追加の CSS ライクな 'sphinxsetup' キー で説明されているカスタマイズをサポートする、より複雑な LaTeX コードに切り替わります。

noteTeXextras, hintTeXextras, importantTeXextras, tipTeXextras

コンテンツの開始時に実行される追加の LaTeX コード（\bfseries や \footnotesize など）。

デフォルト: 空

バージョン 6.2.0 で追加: 7.0.0 まで実験的なものと見なされます。これらのオプションには、追加の CSS ライクな 'sphinxsetup' キー で説明されている div.note_TeXextras (など) というエイリアスがあります。

noteborder, hintborder, importantborder, tipborder

ボーダーの幅。各ボーダー幅を個別に設定できるキーについては、追加の CSS ライクな 'sphinxsetup' キー を参照してください。

デフォルト: 0.5pt

warningBorderColor, cautionBorderColor, attentionBorderColor, dangerBorderColor, errorBorderColor

アドモニションの境界線の色。

デフォルト: {RGB}{148,0,0} (ただし、error は red を使用します)。

バージョン 7.4.0 で変更。

warningBgColor, cautionBgColor, attentionBgColor, dangerBgColor, errorBgColor

注意書きの背景色。

デフォルト: {RGB}{247,247,247}。

バージョン 7.4.0 で変更。

warningborder, cautionborder, attentionborder, dangerborder, errorborder

注意書きの枠の幅。各ボーダー幅を個別に設定できるキーについては、追加の CSS ライクな 'sphinxsetup' キー を参照してください。

デフォルト: 1pt (ただし、error は 1.25pt を使用します)。

バージョン 7.4.0 で変更。

AtStartFootnote

ページの脚注テキストの先頭、脚注番号の後に挿入される LaTeX マクロ。

デフォルト: \mbox{ }

BeforeFootnote

脚注マークの前に挿入される LaTeX マクロ。デフォルトでは、マーク前の不要なスペースを削除します（そうしないと、TeX がそこに改行を挿入する可能性があります）。

デフォルト: \leavevmode\unskip

バージョン 1.5 で追加。

HeaderFamily

デフォルトは \sffamily\bfseries。見出しで使用されるフォントを設定します。

追加の CSS ライクな 'sphinxsetup' キー

バージョン 5.1.0 で追加: code-block、topic、contents ディレクティブ、および強いタイプの注意書き (warning、error など) に適用できます。

バージョン 6.2.0 で追加: note、hint、important、tip の注意書きも、この方法でスタイルを設定できます。リストされているオプションをいずれか使用すると、デフォルトで使用されるものよりも複雑な LaTeX コードが使用されるようになります (sphinxheavybox 対 sphinxlightbox)。新しい noteBgColor (または hintBgColor など) を設定すると、note (または hint など) に sphinxheavybox が使用されるようになります。

バージョン 7.4.0 で追加: すべての注意書きの種類について、デフォルト設定で背景色が設定されるようになりました (そのため、よりリッチな sphinxheavybox が常に使用されます)。

重要

さらに、すべての注意書きのタイトルは、デフォルトで、色付きの行とアイコンを使用してスタイル設定されています。これらは、https://sphinx-doc.dokyumento.jp の Sphinx 自身のドキュメントの現在のレンダリングをモデルにしています。CSS の名前と同様のキーが追加され、タイトルの前景色と背景色、およびアイコンの LaTeX コードを設定できます。

バージョン 7.4.0 で追加: seealso と todo ディレクティブのカスタマイズが可能になりました。

バージョン 8.1.0 で追加: topic、contents、sidebar ディレクティブの個別のカスタマイズと新しいデフォルトが追加されました。

おそらく将来、これらの 5.1.0 (および 6.2.0) の新しい設定は、何らかの正規の CSS 外部ファイルからオプションでインポートされるようになるでしょうが、現在、これらは 'sphinxsetup' インターフェース (または、raw ディレクティブを介して挿入される \sphinxsetup LaTeX コマンド) を介して使用する必要があり、CSS 構文は模倣されているだけです。

重要

入力構文が尊重されない場合、ビルドエラーを引き起こすローレベルの LaTeX エラーが発生する可能性があります。

• 特に、色は、以前に説明した他の色関連のオプションと同様に、つまり \definecolor 構文または \colorlet 構文のいずれかで入力する必要があります。

  ...<other options>
  div.warning_border-TeXcolor={rgb}{1,0,0},% \definecolor syntax
  div.error_background-TeXcolor=red!10,%     \colorlet syntax
  ...<other options>
  

• 等号の代わりにコロンを使用すると、LaTeX が壊れます。

• ...border-width または ...padding は、単一の次元を想定しています。これまでのところ、スペースで区切られた次元で使用することはできません。

• ...top-right-radius などの値は、単一または2 つのスペースで区切られた次元にすることができます。

• 次元指定には、pt、cm、in などの TeX 単位を使用する必要があります。px 単位は、pdflatex および lualatex では認識されますが、xelatex または platex では認識されません。

• このような指定は、「次元式」として、たとえば \fboxsep+2pt や 0.5\baselineskip のように使用することができます。これらの式は、組版時にのみ評価されます。ただし、これらの例のように、TeX の制御シーケンスを使用してバックスラッシュを二重にしたり、‘sphinxsetup’ キーの値に生の Python 文字列を使用する場合は注意してください。

• 原則として、キー値に不要なスペースを挿入することは避けてください。特に半径の場合、2 pt 3pt のような入力をすると、LaTeX が壊れます。\fboxsep \fboxsep は LaTeX ではスペースで区切られたものとは見なされないことにも注意してください。{\fboxsep} \fboxsep のようなものを使用する必要があります。または、原則的に同等でより簡単な 3pt 3pt を直接使用してください。

オプションはすべて、prefix に依存する同様のパターンで名前が付けられており、その後にアンダースコア、そしてプロパティ名が続きます。

ディレクティブ	オプションのプレフィックス	LaTeX 環境
code-block	pre	sphinxVerbatim
literalinclude	pre	sphinxVerbatim
topic	div.topic	sphinxtopic
contents	div.contents	sphinxcontents
sidebar	div.sidebar	sphinxsidebar
note	div.note	sphinxnote
warning	div.warning	sphinxwarning
その他の注意書きの種類 <type>	div.<type>	sphinx<type>
seealso	div.seealso	sphinxseealso
todo	div.todo	sphinxtodo

これらのオプションと、それらの共通のデフォルトを以下に示します。上記で説明したように、<prefix> を実際のプレフィックスに置き換えてください。プレフィックスとプロパティ名を区切るアンダースコアを忘れないでください。

• <prefix>_border-top-width,

  <prefix>_border-right-width,

  <prefix>_border-bottom-width,

  <prefix>_border-left-width,

  <prefix>_border-width。後者は (現在) 単一の次元のみで、4 つの次元すべてを設定します。

  デフォルトでは、これらの次元はすべて等しくなります。それらは以下に設定されます。

  • code-block の場合は 0.4pt

  • topic および contents ディレクティブの場合は 0.5pt

  • sidebar ディレクティブの場合は 1pt

  • note およびその他の「軽い」注意書きの場合は 0.5pt

  • seealso および todo ディレクティブの場合は 0.5pt

  • warning およびその他の「強い」注意書きの場合 (ただし error は 1.25pt を使用) は 1pt。

  バージョン 7.4.0 で変更: topic および error のデフォルトが変更されました。

  バージョン 8.1.0 で変更: topic のデフォルトと区別して、sidebar のデフォルトが設定されました。

• <prefix>_box-decoration-break は、clone または slice のいずれかに設定でき、ページ分割時の動作を設定します。デフォルトでは、code-block (つまり、<prefix>=pre の場合) では 6.0.0 から slice に設定されています。その他のディレクティブでは、デフォルトは clone です。

• <prefix>_padding-top,

  <prefix>_padding-right,

  <prefix>_padding-bottom,

  <prefix>_padding-left,

  <prefix>_padding。後者は（現在） *単一* の寸法のみを指定でき、その寸法が他の4つすべてを設定します。

  デフォルト値は

  • code-block の場合、4つすべてが 3pt、

  • topic の場合、6pt、7pt、6pt、7pt、

  • contents の場合、10pt、7pt、12pt、7pt、

  • sidebar の場合、6pt、5.5pt、6pt、5.5pt、

  • すべての「軽い」注意書き、および seealso と todo ディレクティブの場合、6pt、7pt、6pt、7pt です。

  • error を除く強い注意書きタイプの場合、6pt、6.5pt、6pt、6.5pt で、error は水平パディングに 6.25pt を使用します。

  バージョン 7.4.0 で変更: code-block を除き、すべてのデフォルトが変更されました。注意書きは、左（または右）のパディングと左（または右）のボーダー幅を合計すると常に 7.5pt になるように設定されているため、PDF の同じページで、注意書きタイプ間でコンテンツが垂直方向にうまく整列されます。これはデフォルトの特性に過ぎず、ユーザーが選択できる可能性に対する制約ではありません。

  バージョン 8.1.0 で変更: topic、contents、および sidebar の個別のデフォルト。

• <prefix>_border-top-left-radius,

  <prefix>_border-top-right-radius,

  <prefix>_border-bottom-right-radius,

  <prefix>_border-bottom-left-radius,

  <prefix>_border-radius。この最後のキーは、最初の4つのキーを割り当てられた値に設定します。各キーの値は、単一または *2つ* の寸法で、スペースで区切ることができます。

  デフォルト値は

  • code-block (6.0.0 から) およびすべてのコーナーの場合 3pt、

  • topic のすべてのコーナーの場合、8pt、

  • contents の右下コーナーの場合 12pt で、その他は 0pt を使用、

  • sidebar の左上および右下コーナーの場合 12pt で、右上と左下の場合は 0pt。

  • note、hint、および tip の場合、すべての半径は 5pt に設定され、

  • その他すべてのディレクティブの場合は 0pt、つまり直線的なコーナーです。

  バージョン 7.4.0 で変更: topic と note のような注意書きは、（少なくとも1つの）角が丸くなります。

  バージョン 8.1.0 で変更: topic、contents、および sidebar の個別のデフォルト。

  LaTeX でのスペースによる落とし穴に関する上記の注意を参照してください。

• <prefix>_box-shadow は、以下のように特別な点があります。

  • none キーワードであるか、

  • 単一の寸法（xオフセットとyオフセットの両方を指定）であるか、

  • 2つの寸法（スペースで区切る）であるか、

  • 2つの寸法に続いてキーワード inset が続く場合です。

  xオフセットとyオフセットは負の数でも構いません。負のxオフセットは、影が左側にあることを意味します。影は、オフセットが正であるか負であるかにかかわらず、ページの余白にまで広がります。

  デフォルトは none ですが、contents ディレクティブのみ 4pt 4pt を使用します。

  バージョン 8.1.0 で変更: topic と sidebar のデフォルトでは影はありません。

• <prefix>_border-TeXcolor,

  <prefix>_background-TeXcolor,

  <prefix>_box-shadow-TeXcolor,

  <prefix>_TeXcolor。これらは色です。

  6.0.0 以降、code-block の境界線と背景色は、それぞれデフォルトで {RGB}{32,32,32}（つまり、{HTML}{202020}）と {RGB}{242,242,242}（つまり、{gray}{0.95} または {HTML}{F2F2F2}）になります。

  7.4.0 では、他のディレクティブは黒/白ではないデフォルトの境界線と背景色を取得します。ここでは、xcolor の16進表記（常に6つの16進数が必要）を使用します。

  • {HTML}{F7F7F7} は、すべての背景色として機能します。

  • {HTML}{86989B} は、軽い注意書き（seealso と todo を含む）だけでなく、topic、contents、および sidebar ディレクティブの境界線の色です。

  • {HTML}{940000} は、warning 型の注意書きの境界線の色で、error は {HTML}{B40000} を使用します。

  デフォルトで影を表示するディレクティブは、contents と sidebar だけです。前者の影の色は {HTML}{6C6C6C} で、後者は {HTML}{9EACAF} です。

  <prefix>_TeXcolor は、CSSプロパティ「color」を表します。つまり、コンテンツのテキストの色に影響します。他の3つのオプションと同様に、名前 TeXcolor は、入力構文がHTML/CSSではなくTeXの色用であることを強調するためのものです。LaTeXインストールでパッケージ xcolor が利用可能な場合、キー値として名前付きの色を直接使用できます。latex_elements の 'passoptionstopackages' キーを介して、dvipsnames、svgnames、または x11names などのオプションを xcolor に渡すことを検討してください。

  <prefix>_TeXcolor が設定されている場合、ディレクティブの内容の先頭に \color コマンドが挿入されます。注意書きの場合、これは注意書きタイプを再現する見出しの後に行われます。

• <prefix>_TeXextras：設定した場合、その値は、たとえば \itshape のような、いくつかのLaTeXコマンドである必要があります。これらのコマンドは、コンテンツの先頭に挿入されます。注意書きの場合、これは注意書きタイプを再現する見出しの後に行われます。

注意書き、topic、contents、および sidebar の次のキーは、すべて7.4.0（および後者の3つは8.1.0）で追加されました。

• div.<type>_title-background-TeXcolor：タイトルの背景色。

  重要

  色付きのタイトル行は、さまざまな \sphinxstyle<type>title コマンドのSphinxデフォルト定義の結果として生成され、これらのコマンドは \sphinxdotitlerow LaTeX コマンドを使用します。 マクロ を参照してください。

• div.<type>_title-foreground-TeXcolor: アイコンに使用される色（注意書きのタイトルではなく、アイコンのみに適用されます）。

• div.<type>_title-icon: アイコンを生成するLaTeXコード。例えば、note のデフォルトは div.note_title-icon=\faIcon{info-circle} です。これは、利用可能な場合に自動的にロードされるLaTeXのfontawesome5パッケージのコマンドを使用しています。

  fontawesome5もフォールバックのfontawesome（関連するコマンドは \faIcon ではなく \faicon）も見つからない場合、または‘sphinxsetup’のiconpackageキーが、ユーザーが選択した別のパッケージをロードするように設定されている場合、またはパッケージが全く設定されていない場合、すべてのtitle-iconsはデフォルトで空のLaTeXコードになります。PDF出力にアイコン（またはその他）を挿入するために、このインターフェースを利用するのはユーザー次第です。

注釈

• すべてのディレクティブは、box-decoration-breakをsliceに設定することをサポートしています。

  バージョン 6.2.0 で変更: 以前は、code-blockのみがそうでした。他のすべてのディレクティブのデフォルトはcloneのままですが、7.0.0で変更される可能性があります。

• 角丸ボックスの角は楕円形にすることができます。

  バージョン 6.2.0 で変更: 以前は、円形の角丸のみがサポートされており、角丸はフレーム全体に<prefix>_border-widthから同じ一定の幅を使用するように強制していました。

• 内側の影は角丸とは互換性がありません。両方が指定された場合、内側の影は単純に無視されます。

  バージョン 6.2.0 で変更: 以前は、内側の影が指定された場合に角丸が無視されるという逆の状況でした。

• <prefix>_TeXcolor と <prefix>_TeXextras は 6.2.0 で新たに追加されました。

  code-blockの場合、有用性は疑わしいです。

  • pre_TeXcolor は、Pygmentsでハイライトされていないいくつかのトークンのみに影響します。これは行番号を色付けしますが、*それのみ*を色付けしたい場合は、fancyvrbインターフェースを使用する必要があります。

  • pre_TeXextras=\footnotesize（例として）は、'fvset'キーの値を r'\fvset{fontsize=\footnotesize}' に設定することと同じです。

  これらのオプションは実験的なものであり、実装の詳細が変更される可能性があることを考慮してください。たとえば、Sphinxによってpre_TeXextrasLaTeXコマンドが別の場所に配置された場合、'fvset'の効果が上書きされる可能性があります。おそらくこれは将来のリリースで行われるでしょう。

• 角丸ボックスは、いくつかの基本的なPDFグラフィック操作に対するpict2eインターフェースを使用して行われます。このLaTeXパッケージが見つからない場合、ビルドは続行され、すべてのボックスは直角でレンダリングされます。

• 楕円形の角は、pict2eを拡張するellipseLaTeXパッケージを使用します。このLaTeXパッケージが見つからない場合、角丸は円弧になります（またはpict2eが利用できない場合は直線になります）。

以下のレガシー動作が適用されます。

• code-blockまたはliteralincludeの場合、パディング、ボーダー幅、および（もしあれば）影はマージンに入ります。コード行はパディングとボーダー幅の値に関係なく同じ場所に残ります。ただし、ボーダーまたは外側の影の幅のために他のテキストを上書きしないように、垂直方向にシフトされることはあります。

• 他のディレクティブでは、影はページマージンに水平方向に広がりますが、ボーダーと追加のパディングはテキスト領域内に保持されます。

• code-blockとliteralincludeは同じLaTeX環境とコマンドを使用し、個別にカスタマイズすることはできません。

LaTeXマクロと環境

「LaTeXパッケージ」ファイルsphinx.styは、LaTeXツールチェーンを介してpdfに変換する前のlatexビルダーからの出力で生成されるマークアップで使用される、サポートマクロ（別名コマンド）および環境を提供するさまざまなコンポーネントをロードします。また、「LaTeXクラス」ファイルsphinxhowto.clsとsphinxmanual.clsは、いくつかの環境を定義またはカスタマイズします。これらのファイルはすべて、LaTeXビルドのリポジトリにあります。

これらのいくつかは、既存のLaTeXパッケージでは利用できない機能を提供し、リスト、テーブルセル、逐語的レンダリング、脚注などに関するLaTeXの制限を回避します。

その他は、プリアンブルにユーザーが追加したコンテンツを介してデフォルトを簡単に上書きできるように、パブリック名を持つマクロを定義するだけです。ここではそれらのパブリック名のほとんどを調査しますが、デフォルトはそれぞれの定義ファイルで確認する必要があります。

ヒント

Sphinx LaTeXサポートコードは、複数の小さなサイズのファイルに分割されています。latex_elements['preamble']を介してプリアンブルにコードを追加するのではなく、Sphinx LaTeXコードのコンポーネントファイルの1つをカスタムバージョンで完全に置き換えることもできます。プロジェクトソースに修正されたコピーを含め、ファイル名をlatex_additional_filesリストに追加するだけです。ファイル名と内容については、LaTeXビルドのリポジトリを確認してください。

バージョン 4.0.0 で変更: sphinx.styを複数の小さいユニットに分割し、多くの側面を同時にカスタマイズしやすくしました。

マクロ

• テキストスタイルコマンド

  名前、引数 #1 を以下にマップします:
  \sphinxstrong	\textbf{#1}
  \sphinxcode	\texttt{#1}
  \sphinxbfcode	\textbf{\sphinxcode{#1}}
  \sphinxemail	\textsf{#1}
  \sphinxtablecontinued	\textsf{#1}
  \sphinxtitleref	\emph{#1}
  \sphinxmenuselection	\emph{#1}
  \sphinxguilabel	\emph{#1}
  \sphinxkeyboard	\sphinxcode{#1}
  \sphinxaccelerator	\underline{#1}
  \sphinxcrossref	\emph{#1}
  \sphinxtermref	\emph{#1}
  \sphinxsamedocref	\emph{#1}
  \sphinxparam	\emph{#1}
  \sphinxtypeparam	\emph{#1}
  \sphinxoptional	大きな括弧を使用した[#1]（ソースを参照）

  バージョン 1.4.5 で追加: LaTeXパッケージとの競合の可能性を制限するための\sphinxプレフィックス付きのマクロ名の使用。

  バージョン 1.8 で追加: \sphinxguilabel

  バージョン 3.0 で追加: \sphinxkeyboard

  バージョン 6.2.0 で追加: \sphinxparam、\sphinxsamedocref

  バージョン 7.1.0 で追加: デフォルトでコンマとスペース、および\sphinxparamcommaoneperlineになる\sphinxparamcomma。これは、1行あたりの1つのパラメーターの署名に使用され（maximum_signature_line_lengthを参照）、デフォルトは\texttt{,}です。

  Python関数のシグネチャは、name<space>(parameters) または name<space>[type parameters]<space>(parameters) ( PEP 695 を参照) としてレンダリングされます。ここで、<space> の長さはデフォルトで 0pt に設定されています。これは、例えば \setlength{\sphinxsignaturelistskip}{1ex} を使用して変更できます。

• テキストスタイルの詳細

  名前、引数 #1 を以下にマップします:
  \sphinxstyleindexentry	\texttt{#1}
  \sphinxstyleindexextra	(\emph{#1}) (先頭にスペースあり)
  \sphinxstyleindexpageref	, \pageref{#1}
  \sphinxstyleindexpagemain	\textbf{#1}
  \sphinxstyleindexlettergroup	{\Large\sffamily#1}\nopagebreak\vspace{1mm}
  \sphinxstyleindexlettergroupDefault	ソースを確認してください、ここには長すぎます
  \sphinxstyletopictitle	\textbf{#1}\par\medskip
  \sphinxstylesidebartitle	\textbf{#1}\par\medskip
  \sphinxstyleothertitle	\textbf{#1}
  \sphinxstylesidebarsubtitle	~\\\textbf{#1} \smallskip
  \sphinxstyletheadfamily	\sffamily (これは引数を持たない)
  \sphinxstyleemphasis	\emph{#1}
  \sphinxstyleliteralemphasis	\emph{\sphinxcode{#1}}
  \sphinxstylestrong	\textbf{#1}
  \sphinxstyleliteralstrong	\sphinxbfcode{#1}
  \sphinxstyleabbreviation	\textsc{#1}
  \sphinxstyleliteralintitle	\sphinxcode{#1}
  \sphinxstylecodecontinued	{\footnotesize(#1)}}
  \sphinxstylecodecontinues	{\footnotesize(#1)}}
  \sphinxstylenotetitle	\sphinxdotitlerow{note}{#1}
  \sphinxstylehinttitle	\sphinxdotitlerow{hint}{#1}
  \sphinxstyleimportanttitle	\sphinxdotitlerow{important}{#1}
  \sphinxstyletiptitle	\sphinxdotitlerow{tip}{#1}
  \sphinxstylewarningtitle	\sphinxdotitlerow{warning}{#1}
  \sphinxstylecautiontitle	\sphinxdotitlerow{caution}{#1}
  \sphinxstyleattentiontitle	\sphinxdotitlerow{attention}{#1}
  \sphinxstyledangertitle	\sphinxdotitlerow{danger}{#1}
  \sphinxstyleerrortitle	\sphinxdotitlerow{error}{#1}
  \sphinxstyleseealsotitle	\sphinxdotitlerow{seealso}{#1}
  \sphinxstyletodotitle	\sphinxdotitlerow{todo}{#1}
  \sphinxstyletopictitle	\sphinxdotitlerow{topic}{#1}
  \sphinxstylecontentstitle	\sphinxdotitlerow{contents}{#1}
  \sphinxstylesidebartitle	\sphinxdotitlerow{sidebar}{#1}

  注釈

  この表をPDF出力でページ幅に合わせるために、少しごまかしています。例えば、\sphinxstylenotetitle の実際の定義は

  \newcommand\sphinxstylenotetitle[1]%
  {\sphinxdotitlerow{note}{\sphinxremovefinalcolon{#1}}}
  

  同じ注意が、注意書きに関連する他の同様のコマンドにも当てはまります。topic, contents, および sidebar は、必要ないため \sphinxremovefinalcolon を使用しません。

  バージョン 1.5 で追加: これらのマクロは、以前はカスタマイズできない \texttt, \emph などとしてハードコードされていました。

  バージョン 1.6 で追加: \sphinxstyletheadfamily は、デフォルトで \sffamily であり、テーブルのヘッダーセルで複数の段落を許可します。

  バージョン 1.6.3 で追加: \sphinxstylecodecontinued および \sphinxstylecodecontinues。

  バージョン 1.8 で追加: \sphinxstyleindexlettergroup, \sphinxstyleindexlettergroupDefault。

  バージョン 6.2.0 で追加: \sphinxstylenotetitle など。 #1 は、ディレクティブのローカライズされた名前で、最後にコロンが付いています。最後のコロンを削除する場合は、\sphinxremovefinalcolon{#1} としてラップします。

  バージョン 7.4.0 で追加: \sphinxdotitlerowwithicon LaTeXコマンドを追加しました。

  バージョン 8.1.0 で変更: \sphinxdotitlerowwithicon は、最初引数として使用されるレンダリングされた要素にアイコンが関連付けられているかどうかを自動的に検出するようになりました。

  バージョン 8.1.0 で追加: \sphinxdotitlerow を \sphinxdotitlerowwithicon のエイリアスにします。

  バージョン 8.1.0 で追加: topic, contents, および sidebar ディレクティブのタイトルも \sphinxdotitlerow を使用してスタイル設定されます（デフォルトのアイコンは関連付けられていません）。

• \sphinxtableofcontents: 標準の \tableofcontents のラッパーで、(sphinxhowto.cls および sphinxmanual.cls で異なる定義)。マクロ \sphinxtableofcontentshook は、\tableofcontents 自体の直前の展開中に実行されます。

  バージョン 1.5 で変更: 以前は、\tableofcontents の意味は Sphinx によって変更されていました。

  バージョン 2.0 で変更: 以前に 'manual' docclass の読み込み中に行われていた \l@section および \l@subsection のハードコードされた再定義は、\sphinxtableofcontentshook を介して後で実行されるようになりました。このマクロは 'howto' docclass でも実行されますが、デフォルトでは空です。

  ヒント

  tocloft パッケージの読み込みをプリアンブルに追加する場合は、プリアンブルに \renewcommandsphinxtableofcontentshook{} も追加してください。そうしないと、\l@section および \l@subsection がリセットされ、tocloft のカスタマイズがキャンセルされます。

• \sphinxmaketitle: latex_elements キーの 'maketitle' のデフォルト設定として使用されます。クラスファイル sphinxmanual.cls および sphinxhowto.cls で定義されています。

  バージョン 1.8.3 で変更: 以前は、LaTeX ドキュメントクラスの \maketitle は Sphinx によって変更されていました。

• \sphinxbackoftitlepage: 'manual' docclass の場合、および定義されている場合、最後の \clearpage の前に、\sphinxmaketitle の最後に実行されます。\sphinxbackoftitlepage のカスタム定義を追加するには、latex_elements の 'maketitle' キーまたは 'preamble' キーのいずれかを使用します。

  バージョン 1.8.3 で追加。

• \sphinxcite: 引用参考文献の標準 \cite のラッパー。

\sphinxbox コマンド

バージョン 6.2.0 で追加。

\sphinxbox[key=value,...]{inline text} コマンドは、追加のCSSのような'sphinxsetup'キー で説明されているすべてのカスタマイズを使用して、インラインテキスト要素を「ボックス化」するために使用できます。これは、sphinxsetup設定 の場合と同様に、キー=値ペアのコンマ区切りリストであるオプションの引数を1つ持つ LaTeX コマンドです。キーの完全なリストを以下に示します。接頭辞は使用しません。

• border-width,

• border-top-width, border-right-width, border-bottom-width, border-left-width,

• padding,

• padding-top, padding-right, padding-bottom, padding-left,

• border-radius,

• border-top-left-radius, border-top-right-radius, border-bottom-right-radius, border-bottom-left-radius,

• box-shadow,

• border-TeXcolor, background-TeXcolor, box-shadow-TeXcolor, TeXcolor,

• TeXextras,

• および addstrut で、これはブール値キーです。つまり、addstrut=true、または =true が省略された addstrut 単独、または addstrut=false として使用されます。

この最後のキーは、\sphinxbox に固有のもので、同じ行に異なる内容を持つ複数のインスタンス間で高さと深さを均等にするために、\strut を追加することを意味します。デフォルトは addstrut=false です。addstrut, padding-bottom=0pt, padding-top=1pt の組み合わせがしばしば満足のいく結果をもたらします。

他のキーに関する重要な構文情報については、追加のCSSのような 'sphinxsetup' キーを参照してください。デフォルトの設定では、影がなく、ボーダー幅が \fboxrule、パディングが \fboxsep、半径が \fboxsep の円形の角、そしてコードブロックのデフォルトレンダリングと同じ背景色とボーダー色を使用しています。

\sphinxbox の使用が別の \sphinxbox の中にネストされている場合、外側の \sphinxbox のオプションは無視されます。まず、外側のボックスオプションを適用する前のデフォルト状態にすべてのオプションをリセットし、次に独自のオプションを適用します。

これらのデフォルトは、\sphinxboxsetup{key=value,...} コマンドで変更できます。このコマンドを複数回使用した場合、効果は累積されます。ここで、オプションは必須引数であるため、角括弧ではなく、中括弧の中に記述します。

以下に使用例をいくつか示します。

latex_elements = {
    'preamble': r'''
% modify globally the defaults
\sphinxboxsetup{border-width=2pt,%
                border-radius=4pt,%
                background-TeXcolor=yellow!20}
% configure some styling element with some extra specific options:
\protected\def\sphinxkeyboard#1{\sphinxbox[border-TeXcolor=green]{\sphinxcode{#1}}}
''',
}

ユーティリティ \newsphinxbox は、新しいボックス化マクロを作成するために提供されており、例えば \foo は \sphinxbox とまったく同じように動作しますが、追加の設定が与えられます。

% the specific options to \foo are within brackets
\newsphinxbox[border-radius=0pt, box-shadow=2pt 2pt]{\foo}
% then use this \foo, possibly with some extra options still:
\protected\def\sphinxguilabel#1{\foo{#1}}
\protected\def\sphinxmenuselection#1{\foo[box-shadow-TeXcolor=gray]{#1}}

\foo でレンダリングされたボックスは、\sphinxbox を直接使用する場合と同様に、ドキュメントの途中で \sphinxboxsetup で設定された現在の設定に従います（raw LaTeX マークアップから）。唯一の違いは、初期の追加デフォルト設定があることです。

上記の例では、\protected\def の代わりに \renewcommand 構文を使用することもできます（#1 の代わりに [1] を使用します）。

環境

• figure には、任意の本文要素を持つオプションの凡例を含めることができます。これらは sphinxlegend 環境でレンダリングされます。デフォルトの定義では \small が発行され、\par で終了します。

  バージョン 1.5.6 で追加: 以前は、\small は LaTeX ライターにハードコードされており、末尾の \par が欠落していました。

• 注意喚起に関連付けられた環境

  • sphinxnote,

  • sphinxhint,

  • sphinximportant,

  • sphinxtip,

  • sphinxwarning,

  • sphinxcaution,

  • sphinxattention,

  • sphinxdanger,

  • sphinxerror.

  これらは個別に \renewenvironment で定義することができ、その場合は1つの引数で定義する必要があります（例えば、英語がドキュメント言語である場合の warning ディレクティブの Warning: のように、通知の見出しです）。デフォルトの定義では、sphinxheavybox (最後の5つ) または sphinxlightbox 環境のいずれかを使用し、'sphinxsetup' 文字列で設定できる各タイプに固有のパラメーター（色、ボーダーの太さ）を使用するように構成されています。

  バージョン 1.5 で変更: 公開されている環境名の使用、noteBorderColor、noteborder、warningBgColor、warningBorderColor、warningborder など、パラメーターの個別のカスタマイズ。

• seealso ディレクティブの環境: sphinxseealso。これは、ローカライズされた文字列 See also にコロンを付けたものを引数として受け取ります。

  バージョン 6.1.0 で追加。

  バージョン 6.2.0 で変更: 一般的に注意喚起の処理方法との一貫性を保つため、コロンは環境によって挿入されるのではなく、マークアップの一部になりました。

• todo ディレクティブの環境: sphinxtodo。これは、Todo のローカライズ（最後にコロン付き）を引数として受け取ります（デフォルトのレンダリングでは、そのコロンを削除し、ローカライズされた文字列を独自の色の付いたタイトル行に配置します）。

  バージョン 7.4.0 で追加。

• topic、contents、および sidebar ディレクティブは、それぞれ sphinxtopic、sphinxcontents、および sphinxsidebar 環境に関連付けられています。

  バージョン 1.4.2 で追加: 以前のコードは、改ページを可能にする環境にリファクタリングされました。

  バージョン 1.5 で変更: オプション shadowsep、shadowsize、shadowrule。

  バージョン 8.1.0 で追加: 個別の環境（すべて sphinxShadowBox の周りの3つのラッパー）と、個別のカスタマイズ性。

• リテラルブロック（:: または code-block を介して）、およびリテラルインクルード（literalinclude）は、パッケージ fancyvrb.sty の Verbatim 環境のラッパーである sphinxVerbatim 環境を使用して実装されます。これにより、上部のキャプションの処理、長い行の折り返し、および改ページを可能にするフレームが追加されます。テーブル内では、使用される環境は sphinxVerbatimintable です（フレームは描画されませんが、キャプションは許可されます）。

  バージョン 1.5 で変更: Verbatim は fancyvrb.sty とまったく同じ意味を保持します（OriginalVerbatim という名前でも）。sphinxVerbatimintable はテーブル内で使用されます。

  バージョン 1.5 で追加: オプション verbatimwithframe、verbatimwrapslines、verbatimsep、verbatimborder。

  バージョン 1.6.6 で追加: :emphasize-lines: オプションのサポート

  バージョン 1.6.6 で追加: \sphinxVerbatimHighlightLine など、ユーザーに公開された LaTeX マクロを介した書式の簡単なカスタマイズ。

• 参考文献は sphinxthebibliography を使用し、Python モジュールインデックスと一般的なインデックスの両方で sphinxtheindex を使用します。これらの環境は、ドキュメントクラス（またはパッケージ）によって提供される thebibliography 環境とそれぞれ theindex 環境のラッパーです。

  バージョン 1.5 で変更: 以前は、元の環境は Sphinx によって変更されていました。

その他

• ドキュメント本文のすべてのテキスト段落は、\sphinxAtStartPar で始まります。現在、これは、狭いコンテキスト（テーブルセルなど）で段落の最初の単語の TeX ハイフネーションを許可するトリックであるゼロ幅の水平スキップを挿入するために使用されます。トリックを必要としない 'lualatex' の場合、\sphinxAtStartPar は何も行いません。

  バージョン 3.5.0 で追加。

• セクション、サブセクション、...の見出しは、titlesec の \titleformat コマンドを使用して設定されます。

• 'manual' docclass の場合、章の見出しは、fncychap のコマンド \ChNameVar、\ChNumVar、\ChTitleVar を使用してカスタマイズできます。ファイル sphinx.sty には、fncychap オプション Bjarne の場合のカスタム再定義があります。

  バージョン 1.5 で変更: 以前は、Bjarne 以外のスタイルで fncychap を使用すると機能不全でした。

• バージョン 8.1.0 で変更:カスタムロールを介して複数のクラスが挿入された場合、LaTeX出力は、Docutilsドキュメントにあるように、ネストされた\DUroleを使用します。以前は、コンマ区切りのクラスを持つ単一の\DUroleを使用しており、LaTeXのカスタマイズがより困難でした。

• \newenvironment{sphinxclassred}{\color{red}}{}
  

  現在、クラス名にはASCII文字のみを含める必要があり、\などのLaTeXに特殊な文字は避けてください。

  バージョン 4.1.0 で追加。

ヒント

試験的な機能として、プロジェクトに_templates/latex.tex.jinjaという名前のファイルがある場合、SphinxはLaTeXソースにユーザー定義のテンプレートファイルを使用できます。

テーブルのレンダリング（キャプションの位置など）のいくつかの側面を設定するために、追加のファイルlongtable.tex.jinja、tabulary.tex.jinja、およびtabular.tex.jinjaを_templates/に追加できます。

バージョン 1.6 で追加:現在、すべてのテンプレート変数は不安定であり、ドキュメント化されていません。

バージョン 7.4 で変更:.jinjaファイル拡張子のサポートが追加されました。これは推奨されています。古いファイル名も引き続きサポートされています。（latex.tex_t、longtable.tex_t、tabulary.tex_t、およびtabular.tex_t）

前へ

非推奨のAPI

次へ

サポートを受ける