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 字串字面值中，反斜線必須加倍，以避免被解釋為跳脫序列。或者，您可以如上例所示使用原始字串。

The `latex_elements` 設定選項¶

一個字典，其中包含 LaTeX 片段，用於覆寫 Sphinx 通常放入產生的 .tex 檔案中的內容。其 '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 引擎的支援，對於某些語言，可能更適合選擇 babel 而非 polyglossia。

提示

在修改像這樣的核心 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')，預設值是使用 babel，而不是 polyglossia。

在版本 7.4.0 中變更：對於法語，使用 'lualatex'，預設值是使用 babel。

'fontpkg'

字型套件包含。使用 'pdflatex' 的預設值為

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

另一方面，對於 'xelatex' 和 'lualatex'，LaTeX 套件 fontspec (透過 'fontenc' 包含) 的 \setmainfont、\setsansfont 和 \setmonofont 指令用於設定 OpenType 字型 GNU FreeSerif、FreeSans 和 FreeMono (以比例 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 載入。這取代了先前透過 'fvset' 設定程式碼區塊使用 \small 的機制。行內文字現在更適合其周圍的文字，並且更容易設定自訂字型，因為預設情況下 '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}'，否則為 ''。

注意

如果使用 utf8x 代替 utf8，則必須按照 utf8x 文件 (在基於 TeXLive 的 TeX 安裝上使用 texdoc ucs) 的說明，使用適當的 \PreloadUnicodePage{<number>} 指令擴充 LaTeX 序言。否則，可能會在 PDF 中出現意外且可能難以發現的問題 (即不會導致建置崩潰)，特別是關於超連結。

即使採取了這些預防措施，由於上游 LaTeX 與 utf8x 不完全相容，透過 pdflatex 引擎建置 PDF 仍可能崩潰。例如，在某些與程式碼區塊相關的情況下，或嘗試包含檔案名稱包含 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' 額外執行 \defaultfontfeatures[\rmfamily,\sffamily]{} 以停用 << 和 >> 的 TeX 連字。

在版本 2.0 中變更：如果在此鍵中偵測到 LGR、T2A 或 X2，則會自動執行額外的 LaTeX 設定，以便在使用 'pdflatex' 時支援偶爾出現的希臘文或西里爾字母。

在版本 2.2.1 中變更：以希臘文作為主要語言的文件預設為 'xelatex'，並且不應設定 'fontenc' 鍵，這將載入 fontspec。

在版本 2.3.0 中變更：'xelatex' 執行 \defaultfontfeatures[\rmfamily,\sffamily]{} 以避免將 -- 收縮為 en-dash，並避免將直引號轉換為彎引號 (即使將 smartquotes 設定為 False，否則也會發生)。

'fontsubstitution'

如果 'fontenc' 未配置為使用 LGR 或 X2 (或 T2A)，則會忽略。如果 'fontpkg' 鍵配置為與已知在 LGR 或 X2 編碼中可用的某些 TeX 字型一起使用，請將此鍵設定為空字串。否則，請保留其預設值。

使用 latex_engine (而非 'pdflatex') 時會忽略。

在版本 4.0.0 中新增。

'textgreek'

為了支援偶爾出現的希臘字母。

使用 'platex'、'xelatex' 或 'lualatex' 作為 latex_engine 時會忽略，並且預設為空字串或 r'\usepackage{textalpha}' (對於 'pdflatex')，具體取決於 'fontenc' 鍵是否與 LGR 一起使用。只有專業的 LaTeX 使用者可能想要自訂此鍵。

它也可以用作 r'\usepackage{textalpha,alphabeta}'，以讓 'pdflatex' 在 math 環境中支援希臘文 Unicode 輸入。例如，:math:`α` (U+03B1) 將呈現為 \(\alpha\)。

預設值：如果 fontenc 不包含 LGR 選項，則為 r'\usepackage{textalpha}' 或 ''。

在版本 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> 將在標題頁的背面排版 (僅限 '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 的包裝器，它本身可以由使用者載入的套件自訂。如果您想產生不同的目錄，或在標題頁和 TOC 之間放置內容，請覆寫。

預設值：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' 索引將只使用一欄。您可能需要安裝 idxlayout LaTeX 套件。

預設值： r'\makeindex'

'printindex'

“printindex” 呼叫，檔案中的最後一件事。如果您想要以不同的方式產生索引、在索引後附加一些內容或更改字體，請覆寫此項。由於 LaTeX 為索引使用雙欄模式，因此通常建議將此鍵設置為 r'\footnotesize\raggedright\printindex'。或者，要獲得單欄索引，請使用 r'\def\twocolumn[#1]{#1}\printindex' （如果使用自訂文件類別，此技巧可能會失敗；然後嘗試 idxlayout 方法，詳見 'makeindex' 鍵的文件）。

預設值： 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'，預設值為 r'\fvset{fontsize=\small}'，因為這適用於 FreeFont 字體系列的相對寬度。

版本 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,...}

可以透過 raw 指令將 \sphinxsetup LaTeX 巨集的使用直接插入到文件的主體中

.. 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 頂部找到。

上述範例中使用的顏色可從將 svgnames 選項傳遞給 “xcolor” 套件獲得

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

bookmarksdepth

控制 PDF 中可摺疊書籤面板的深度。可以是數字（例如 3）或 LaTeX 分節名稱（例如 subsubsection，即不帶反斜線）。有關詳細資訊，請參閱 hyperref LaTeX 文件。

預設值： 5

在版本 4.0.0 中新增。

hmargin, vmargin

水平（resp. 垂直）邊距的尺寸，作為 hmargin （resp. vmargin）選項傳遞給 geometry 套件。範例

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

日文文件目前僅接受這些參數的一維格式。geometry 套件隨後會傳遞適當的選項，使文字寬度設定為全形寬度的精確倍數，而文字高度設定為基線間距的整數倍數，並為邊距提供最接近的擬合。

預設值： 1in （相當於 {1in,1in}）

提示

對於日文 'manual' 文件類別，點大小為 11pt 或 12pt，請使用 nomag 額外文件類別選項（參見 latex_elements 的 'extraclassoptions' 鍵）或所謂的 TeX “真實” 單位

'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 未與其 texcomments 或類似選項一起使用，這些選項允許額外的（任意）LaTeX 標記。

此外，如果 latex_engine 設定為 'pdflatex'，則僅允許預設 LaTeX 處理 Unicode 碼位，即 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

布林值，用於指定程式碼區塊在換頁時是否顯示 “continued on next page”（下一頁繼續）和 “continued from previous page”（從上一頁繼續）提示。

預設值： 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 命令設定或修改，也可以從與容器類別關聯並使用此類 \sphinxsetup{...} 的 LaTeX 環境設定或修改。

預設值： {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

程式碼行與框架之間的間隔。

請參閱額外的類 CSS 'sphinxsetup' 鍵以取得其別名 pre_padding 和其他鍵。

預設值： \fboxsep

verbatimborder

code-block 周圍框架的寬度。另請參閱額外的類 CSS 'sphinxsetup' 鍵以取得 pre_border-width。

預設值： \fboxrule

重要事項

自 8.1.0 起，可以分別樣式化 topic、contents 和 sidebar 指令，且它們的預設值不同。請參閱額外的類 CSS 'sphinxsetup' 鍵。接下來的三個鍵保留為舊版介面，不區分這三個指令。

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 的通用圖示將預設為 “bolt” 而不是 “radiation”，後者僅在 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 切換到更複雜的 LaTeX 程式碼，該程式碼支援額外的類 CSS 'sphinxsetup' 鍵中描述的自訂性。

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 vs sphinxlightbox)。設定新的 noteBgColor (或 hintBgColor, …) 也會針對 note (或 hint, …) 觸發使用 sphinxheavybox。

版本 7.4.0 新增：對於所有警示框類型，預設設定會設定背景顏色 (因此總是使用更豐富的 sphinxheavybox)。

重要事項

此外，所有警示框標題預設都會使用彩色列和圖示來設定樣式，其樣式模仿 Sphinx 官方文件在 https://sphinx-doc.dev.org.tw 上的當前呈現方式。新增了類似 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 等值可以是單一或兩個空格分隔的尺寸。
尺寸規格必須使用 TeX 單位，例如 pt、cm 或 in。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。後者（目前）只能是單一尺寸，然後設定所有其他四個尺寸。

預設情況下，所有這些尺寸都相等。它們被設定為：
- 0.4pt 用於 code-block，
- 0.5pt 用於 topic 和 contents 指令，
- 1pt 用於 sidebar 指令，
- 0.5pt 用於 note 和其他「輕量」警示框，
- 0.5pt 用於 seealso 和 todo 指令，
- 1pt 用於 warning 和其他「強型態」警示框，但 error 例外，它使用 1.25pt。
版本 7.4.0 變更：變更 topic 和 error 的預設值。

版本 8.1.0 變更：sidebar 的預設值與 topic 不同。
<prefix>_box-decoration-break 可以設定為 clone 或 slice，並設定分頁符號的行為。自 6.0.0 版本以來，code-block (即 <prefix>=pre) 的預設值為 slice。對於其他指令，預設值為 clone。
<prefix>_padding-top,

<prefix>_padding-right,

<prefix>_padding-bottom,

<prefix>_padding-left,

<prefix>_padding。後者（目前）只能是單一尺寸，然後設定所有其他四個尺寸。

預設值：
- 所有四個邊距皆為 3pt，用於 code-block，
- 6pt、7pt、6pt、7pt 用於 topic，
- 10pt、7pt、12pt、7pt 用於 contents，
- 6pt、5.5pt、6pt、5.5pt 用於 sidebar，
- 6pt、7pt、6pt、7pt 用於所有「輕量」警示框以及 seealso 和 todo 指令。
- 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。最後一個鍵將前四個鍵設定為其指定的值。每個鍵值可以是單一或兩個空格分隔的尺寸。

預設值：
- 3pt 用於 code-block (自 6.0.0 版本以來) 和所有角，
- 8pt 用於 topic 的所有角，
- 12pt 用於 contents 的右下角，其他角使用 0pt，
- 12pt 用於 sidebar 的左上角和右下角，右上角和左下角為 0pt。
- 所有半徑都設定為 5pt，用於 note、hint 和 tip，
- 0pt，即所有其他指令的直角。
版本 7.4.0 變更：topic 和類似 note 的警示框取得 (至少一個) 圓角。

版本 8.1.0 變更：針對 topic、contents 和 sidebar 提供個別的預設值。

請參閱上面關於 LaTeX 中空格陷阱的註解。
<prefix>_box-shadow 很特別，因為它可能是：
- none 關鍵字，
- 或單一尺寸 (同時給定 x 偏移量和 y 偏移量)，
- 或兩個尺寸 (以空格分隔)，
- 或兩個尺寸，後接關鍵字 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 十六進位標記法 (總是需要 6 個十六進位數字)：
- {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」，即它會影響內容的文字顏色。至於其他三個選項，命名為 TeXcolor 是為了強調輸入語法是 TeX 的顏色語法，而不是 HTML/CSS 語法。如果 LaTeX 安裝中提供了 xcolor 套件，則可以直接使用命名的顏色作為鍵值。考慮透過 latex_elements 的 'passoptionstopackages' 鍵將例如 dvipsnames、svgnames 或 x11names 等選項傳遞給 xcolor。

如果設定了 <prefix>_TeXcolor，則會在指令內容的開頭插入 \color 命令；對於警示框，這會在重現警示框類型的標題之後發生。
<prefix>_TeXextras：如果設定了，其值必須是一些 LaTeX 命令，例如 \itshape。這些命令將在內容的開頭插入；對於警示框，這會在重現警示框類型的標題之後發生。

接下來的鍵，用於警示框、topic、contents 和 sidebar，都是在 7.4.0 版本 (後三者在 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_TeXextras LaTeX 命令放在另一個位置，它可能會覆寫 'fvset' 的效果，這或許是未來版本會做的事情。
圓角框是使用 pict2e 介面來完成的，該介面連接到一些基本的 PDF 圖形操作。如果找不到此 LaTeX 套件，建置將繼續進行，並以直角渲染所有框。
橢圓角使用延伸 pict2e 的 ellipse LaTeX 套件。如果找不到此 LaTeX 套件，圓角將為圓弧 (如果 pict2e 不可用，則為直線)。

以下適用於舊版行為：

對於 code-block 或 literalinclude，邊距和邊框寬度以及陰影 (如果有的話) 將進入邊距；程式碼行保持在相同的位置，獨立於邊距和邊框寬度的值，除非當然會垂直移動，以避免因邊框或外部陰影的寬度而覆寫其他文字。
對於其他指令，陰影會水平延伸到頁面邊距中，但邊框和額外的邊距會保留在文字區域內。
code-block 和 literalinclude 使用相同的 LaTeX 環境和命令，並且無法單獨自訂。

LaTeX 巨集和環境¶

「LaTeX 套件」檔案 sphinx.sty 載入各種組件，這些組件提供支援巨集 (又稱命令) 和環境，這些巨集和環境用於從 latex 建置器產生的標記中，在透過 LaTeX 工具鏈轉換為 pdf 之前。此外，「LaTeX 類別」檔案 sphinxhowto.cls 和 sphinxmanual.cls 定義或自訂了一些環境。所有這些檔案都可以在 latex 建置目錄中找到。

其中一些提供了預先存在的 LaTeX 套件無法提供的功能，並解決了 LaTeX 在列表、表格儲存格、逐字呈現、註腳等方面的限制。

其他套件只是簡單地定義具有公用名稱的巨集，以便透過使用者添加到前言的內容輕鬆覆寫其預設值。我們將在此處調查大多數這些公用名稱，但預設值必須在其各自的定義檔案中查看。

提示

Sphinx LaTeX 支援程式碼分散在多個較小的檔案中。與其透過 latex_elements['preamble'] 將程式碼添加到前言中，也可以完全替換 Sphinx LaTeX 程式碼的其中一個組件檔案，只需在專案來源中包含修改後的副本，並將檔案名稱添加到 latex_additional_files 列表中。檢查 LaTeX 建置目錄以取得檔案名稱和內容。

版本 4.0.0 變更：將 sphinx.sty 分割成多個較小的單元，以方便同時自訂多個方面。

巨集¶

文字樣式命令

名稱， `maps argument #1 to:`
`\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]` 使用較大的括號，請參閱原始碼

Added in version 1.4.5: 使用 \sphinx 前綴的巨集名稱，以限制與 LaTeX 套件衝突的可能性。

Added in version 1.8: \sphinxguilabel

Added in version 3.0: \sphinxkeyboard

Added in version 6.2.0: \sphinxparam, \sphinxsamedocref

Added in version 7.1.0: \sphinxparamcomma，預設為逗號後接一個空格，以及 \sphinxparamcommaoneperline。它用於每行一個參數的簽名（請參閱 maximum_signature_line_length），預設為 \texttt{,}。

Python 函數的簽名呈現為 name<space>(parameters) 或 name<space>[type parameters]<space>(parameters) (請參閱 PEP 695)，其中 <space> 的長度預設設定為 0pt。這可以通過 \setlength{\sphinxsignaturelistskip}{1ex} 等方式更改。

更多文字樣式

名稱， `maps argument #1 to:`
`\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，因為它們不需要。

Added in version 1.5: 這些巨集以前被硬編碼為不可自訂的 \texttt、\emph 等…

Added in version 1.6: \sphinxstyletheadfamily，預設為 \sffamily，並允許表格標題單元格中有多個段落。

Added in version 1.6.3: \sphinxstylecodecontinued 和 \sphinxstylecodecontinues。

Added in version 1.8: \sphinxstyleindexlettergroup、\sphinxstyleindexlettergroupDefault。

Added in version 6.2.0: \sphinxstylenotetitle 等。#1 是指令的本地化名稱，帶有結尾冒號。如果需要移除結尾冒號，請將其包裝為 \sphinxremovefinalcolon{#1}。

Added in version 7.4.0: 新增 \sphinxdotitlerowwithicon LaTeX 命令。

Changed in version 8.1.0: \sphinxdotitlerowwithicon 現在會自動偵測是否有名稱與作為第一個參數呈現的元素相關聯的圖示。

Added in version 8.1.0: 將 \sphinxdotitlerow 設定為 \sphinxdotitlerowwithicon 的別名。

Added in version 8.1.0: topic、contents 和 sidebar 指令的標題也使用 \sphinxdotitlerow 進行樣式設定（它們沒有與之關聯的預設圖示）。

\sphinxtableofcontents：標準 \tableofcontents 的包裝器（在 sphinxhowto.cls 和 sphinxmanual.cls 中以不同方式定義）。巨集 \sphinxtableofcontentshook 在其展開期間，緊接在 \tableofcontents 本身之前執行。

Changed in version 1.5: 以前，\tableofcontents 的含義由 Sphinx 修改。

Changed in version 2.0: 以前在載入 'manual' docclass 期間硬編碼重新定義的 \l@section 和 \l@subsection，現在稍後通過 \sphinxtableofcontentshook 執行。此巨集也由 'howto' docclass 執行，但預設為空。

提示

如果在前言中新增載入 tocloft 套件，也請在前言中新增 \renewcommandsphinxtableofcontentshook{}，否則它將重設 \l@section 和 \l@subsection，取消 tocloft 自訂。
\sphinxmaketitle：用作 'maketitle' latex_elements 鍵的預設設定。在類別檔案 sphinxmanual.cls 和 sphinxhowto.cls 中定義。

Changed in version 1.8.3: 以前，LaTeX 文件類別中的 \maketitle 由 Sphinx 修改。
\sphinxbackoftitlepage：對於 'manual' docclass，如果已定義，則在 \sphinxmaketitle 結尾處執行，在最終的 \clearpage 之前。使用 latex_elements 的 'maketitle' 鍵或 'preamble' 鍵來新增 \sphinxbackoftitlepage 的自訂定義。

Added in version 1.8.3.
\sphinxcite：標準 \cite 的包裝器，用於引用參考文獻。

`\sphinxbox` 命令¶

版本 6.2.0 新增。

\sphinxbox[key=value,...]{inline text} 命令可用於「框住」行內文字元素，並具有額外的 CSS 類別 'sphinxsetup' 鍵中描述的所有自訂功能。它是一個 LaTeX 命令，帶有一個可選參數，該參數是以逗號分隔的 key=value 對列表，如 sphinxsetup 配置設定所示。以下是完整的鍵列表。它們不使用任何前綴。

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 (邊框 TeX 顏色)、background-TeXcolor (背景 TeX 顏色)、box-shadow-TeXcolor (陰影 TeX 顏色)、TeXcolor (TeX 顏色)、
TeXextras (額外的 TeX 設定),
和 addstrut，這是一個布林值鍵，即用作 addstrut=true，或僅使用 addstrut，其中省略了 =true，或 addstrut=false。

最後一個鍵是 \sphinxbox 特有的，它表示新增一個 \strut，以便在同一行上具有不同內容的各種實例之間，高度和深度相等。預設值為 addstrut=false。addstrut, padding-bottom=0pt, padding-top=1pt 的組合通常令人滿意。

有關其他鍵的重要語法資訊，請參閱額外的 CSS 類別 'sphinxsetup' 鍵。預設配置不使用陰影，邊框寬度為 \fboxrule，內邊距為 \fboxsep，圓角半徑為 \fboxsep，背景和邊框顏色與程式碼區塊的預設呈現方式相同。

當 \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 標記）在文件中途設定，唯一的區別是它們具有初始的額外預設設定集。

在上面的範例中，如果您更喜歡 \renewcommand 語法而不是 \protected\def，則可能可以使用 \renewcommand 語法（然後用 [1] 代替 #1）。

環境¶

figure 可能有一個可選的圖例，其中包含任意主體元素：它們在 sphinxlegend 環境中呈現。預設定義發出 \small，並以 \par 結尾。

Added in version 1.5.6: 以前，\small 是在 LaTeX 寫入器中硬編碼的，並且缺少結尾的 \par。
與提示框相關的環境
- sphinxnote,
- sphinxhint,
- sphinximportant,
- sphinxtip,
- sphinxwarning,
- sphinxcaution,
- sphinxattention,
- sphinxdanger,
- sphinxerror.
可以個別 \renewenvironment 它們，然後必須使用一個參數定義（它是通知的標題，例如 warning 指令的 Warning:，如果文件語言是英語）。它們的預設定義使用 sphinxheavybox（用於最後 5 個）或 sphinxlightbox 環境，配置為使用每種類型特定的參數（顏色、邊框粗細），這些參數可以通過 'sphinxsetup' 字串設定。

Changed in version 1.5: 使用公用環境名稱，參數的獨立自訂性，例如 noteBorderColor、noteborder、warningBgColor、warningBorderColor、warningborder、…
seealso 指令的環境：sphinxseealso。它接受一個參數，該參數將是本地化字串 See also 後面跟著冒號。

Added in version 6.1.0.

Changed in version 6.2.0: 冒號成為標記的一部分，而不是由環境插入，以便與一般處理提示框的方式保持一致。
todo 指令的環境：sphinxtodo。它接受一個參數，即 Todo 的本地化（結尾帶有冒號；預設呈現方式將移除該冒號，並將本地化字串放在其自身的彩色標題列中）。

版本 7.4.0 新增。
topic、contents 和 sidebar 指令分別與 sphinxtopic、sphinxcontents 和 sphinxsidebar 環境相關聯。

Added in version 1.4.2: 以前的程式碼重構為允許分頁符號的環境。

Changed in version 1.5: 選項 shadowsep、shadowsize、shadowrule。

Added in version 8.1.0: 獨立的環境（所有三個都是 sphinxShadowBox 的包裝器）和獨立的自訂性。
文字區塊（透過 :: 或 code-block）和文字包含（literalinclude）是使用 sphinxVerbatim 環境實作的，該環境是套件 fancyvrb.sty 中的 Verbatim 環境的包裝器。它新增了頂部標題的處理和長行的換行，以及允許分頁符號的框架。在表格內部，使用的環境是 sphinxVerbatimintable（它不繪製框架，但允許標題）。

Changed in version 1.5: Verbatim 保留與 fancyvrb.sty 中完全相同的含義（在名稱 OriginalVerbatim 下也是如此）；sphinxVerbatimintable 在表格內部使用。

Added in version 1.5: 選項 verbatimwithframe、verbatimwrapslines、verbatimsep、verbatimborder。

Added in version 1.6.6: 支援 :emphasize-lines: 選項

Added in version 1.6.6: 通過向使用者公開 LaTeX 巨集（例如 \sphinxVerbatimHighlightLine），更容易自訂格式。
參考書目使用 sphinxthebibliography，Python 模組索引以及一般索引都使用 sphinxtheindex；這些環境是文件類別（或套件）提供的 thebibliography 和 theindex 環境的包裝器。

Changed in version 1.5: 以前，原始環境由 Sphinx 修改。

雜項¶

文件主體中的每個文字段落都以 \sphinxAtStartPar 開頭。目前，這用於插入零寬度水平跳過，這是一種技巧，允許 TeX 在狹窄的上下文中（如表格單元格）對段落的第一個單字進行斷字。對於不需要此技巧的 'lualatex'，\sphinxAtStartPar 不執行任何操作。

版本 3.5.0 新增。
章節、小節、…標題使用 titlesec 的 \titleformat 命令設定。
對於 'manual' docclass，章節標題可以使用 fncychap 的命令 \ChNameVar、\ChNumVar、\ChTitleVar 進行自訂。檔案 sphinx.sty 在 fncychap 選項 Bjarne 的情況下具有自訂的重新定義。

Changed in version 1.5: 以前，將 fncychap 與 Bjarne 以外的樣式一起使用會發生故障。
role 指令允許使用類別參數標記行內文字。這在 LaTeX 輸出中通過 Docutils 中的 \DUrole 調度命令處理。物件簽名也使用 \DUrole 用於某些元件，類別名稱為一個或兩個字母，如 HTML 輸出中所示。

Changed in version 8.1.0: 當通過自訂角色注入多個類別時，LaTeX 輸出使用巢狀 \DUrole，如 Docutils 文件中所示。以前，它使用帶有逗號分隔類別的單個 \DUrole，使得 LaTeX 自訂更加困難。

LaTeX 輸出中支援 Docutils container 指令：為了讓類別名稱為 foo 的容器通過 LaTeX 影響最終 PDF，只需要在前言中定義環境 sphinxclassfoo。一個簡單的範例是
```
\newenvironment{sphinxclassred}{\color{red}}{}
```
目前，類別名稱必須僅包含 ASCII 字元，並避免 LaTeX 特殊字元，例如 \。

Added in version 4.1.0.

提示

作為一個實驗性功能，如果您在專案中有名為 _templates/latex.tex.jinja 的檔案，Sphinx 可以使用使用者定義的範本檔案作為 LaTeX 來源。

可以將其他檔案 longtable.tex.jinja、tabulary.tex.jinja 和 tabular.tex.jinja 新增到 _templates/，以配置表格呈現的某些方面（例如標題位置）。

Added in version 1.6: 目前，所有範本變數都不穩定且未記錄在案。

Changed in version 7.4: 新增對 .jinja 檔案擴展名的支援，這是首選的。舊檔案名稱仍然支援。（latex.tex_t、longtable.tex_t、tabulary.tex_t 和 tabular.tex_t）

LaTeX 自訂¶

The latex_elements 設定選項¶

sphinxsetup 組態設定¶

額外的類 CSS 'sphinxsetup' 鍵¶

LaTeX 巨集和環境¶

巨集¶

\sphinxbox 命令¶

環境¶

雜項¶

The `latex_elements` 設定選項¶

`sphinxsetup` 組態設定¶

額外的類 CSS `'sphinxsetup'` 鍵¶

`\sphinxbox` 命令¶