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 字符串字面量中，反斜杠必须加倍，以避免被解释为转义序列。或者，你可以使用原始字符串，如上例所示。

`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'

除非在特殊情况下，否则不需要覆盖的键包括

'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 中出现意外且可能难以发现的问题（即不会导致构建崩溃），尤其是在超链接方面。

即使采取了这些预防措施，通过 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'

对于 'pdflatex' 作为 latex_engine，其默认值为 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 的包装器，\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'，索引将仅使用一列。你可能需要安装 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})

提示

对于点大小为 11pt 或 12pt 的日语 'manual' 文档类，请使用 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 未使用其 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",
}

这可以通过使用原始 latex 指令将合适的 \sphinxsetup（之前和之后）插入到 latex 文件中，针对给定的代码块在本地完成。

默认值：100

在版本 3.5.0 中添加。

verbatimhintsturnover

布尔值，用于指定代码块在发生分页符时是否显示“下页继续”和“上页继续”提示。

默认值：true

在版本 1.6.3 中添加。

在版本 1.7 中更改：默认值从 false 更改为 true。

verbatimcontinuedalign, verbatimcontinuesalign

相对于带框内容Horizontal position：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

代码行和边框之间的分隔。

有关其别名 pre_padding 和其他键，请参阅其他类似 CSS 的 'sphinxsetup' 键。

默认值：\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，这意味着不会尝试加载任何包。独立于此设置，任意 LaTeX 代码可以通过 div.<type>_icon-title 键与每种告诫类型关联，这些键在其他类似 CSS 的 'sphinxsetup' 键部分中描述。如果未使用这些键，Sphinx 将应用其默认的图标选择（如果 fontawesome{5,} 可用）或根本不绘制图标。请注意，如果使用备用 fontawesome，则 caution 和 danger 的通用图标将默认为 “bolt” 而不是 “radiation”，后者仅在 fontawesome5 中找到。

在版本 7.4.0 中添加。

noteBorderColor, hintBorderColor, importantBorderColor, tipBorderColor

告诫边框的颜色。

默认值：{RGB}{134,152,155}。

Changed in version 7.4.0.

noteBgColor, hintBgColor, importantBgColor, tipBgColor

告诫背景的颜色。

默认值：{RGB}{247,247,247}。

在版本 6.2.0 中添加。

Changed in version 7.4.0.

noteTextColor, hintTextColor, importantTextColor, tipTextColor

告诫内容的颜色。

默认值：未设置（内容文本使用环境文本颜色，先验为黑色）

在版本 6.2.0 中添加：在 7.0.0 版本之前被认为是实验性的。这些选项具有别名 div.note_TeXcolor (等等)，在其他类似 CSS 的 'sphinxsetup' 键中描述。使用后者将使 Sphinx 切换到更复杂的 LaTeX 代码，该代码支持其他类似 CSS 的 'sphinxsetup' 键中描述的自定义功能。

noteTeXextras, hintTeXextras, importantTeXextras, tipTeXextras

一些额外的 LaTeX 代码（例如 \bfseries 或 \footnotesize）在内容开始时执行。

默认值：空

在版本 6.2.0 中添加：在 7.0.0 版本之前被认为是实验性的。这些选项具有别名 div.note_TeXextras (等等)，在其他类似 CSS 的 'sphinxsetup' 键中描述。

noteborder, hintborder, importantborder, tipborder

边框的宽度。有关允许分别配置每个边框宽度的键，请参阅其他类似 CSS 的 'sphinxsetup' 键。

默认值：0.5pt

warningBorderColor, cautionBorderColor, attentionBorderColor, dangerBorderColor, errorBorderColor

告诫边框的颜色。

默认值：{RGB}{148,0,0}，但 error 除外，后者使用 red。

Changed in version 7.4.0.

warningBgColor, cautionBgColor, attentionBgColor, dangerBgColor, errorBgColor

告诫背景的背景颜色。

默认值：{RGB}{247,247,247}。

Changed in version 7.4.0.

warningborder, cautionborder, attentionborder, dangerborder, errorborder

告诫边框的宽度。有关允许分别配置每个边框宽度的键，请参阅其他类似 CSS 的 'sphinxsetup' 键。

默认值：1pt，但 error 除外，后者使用 1.25pt。

Changed in version 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）。

重要提示

此外，默认情况下，所有提示框标题都使用彩色行和图标设置样式，这些样式模仿了 Sphinx 官方文档在 https://sphinx-doc.cn 上的当前渲染效果。添加了类似 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 版本更改: 与 topic 的默认值不同，sidebar 有单独的默认值。
<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（边框 TeX 颜色）,

<prefix>_background-TeXcolor（背景 TeX 颜色）,

<prefix>_box-shadow-TeXcolor（阴影 TeX 颜色）,

<prefix>_TeXcolor（TeX 颜色）。这些是颜色。

自 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 在列表、表格单元格、verbatim 渲染、脚注等方面的限制。

有些人只是简单地定义带有公共名称的宏，以便用户可以通过添加到导言区的内容轻松覆盖它们的默认值。我们将在本文中调查大多数这些公共名称，但默认值必须在其各自的定义文件中查看。

提示

Sphinx LaTeX 支持代码被拆分到多个较小的文件中。除了通过 latex_elements['preamble'] 将代码添加到导言区之外，还可以通过在项目源中包含修改后的副本并将文件名添加到 latex_additional_files 列表中，完全替换 Sphinx LaTeX 代码的组件文件之一。请查看 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]`，带有更大的括号，请参阅源代码

在 1.4.5 版本中新增: 使用 \sphinx 前缀的宏名称，以限制与 LaTeX 包冲突的可能性。

在 1.8 版本中新增: \sphinxguilabel

在 3.0 版本中新增: \sphinxkeyboard

在 6.2.0 版本中新增: \sphinxparam, \sphinxsamedocref

在 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，因为它们不需要它。

在 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' 文档类期间完成的 \l@section 和 \l@subsection 的硬编码重定义现在稍后通过 \sphinxtableofcontentshook 执行。 'howto' 文档类也执行此宏，但在其中默认为空。

提示

如果将 tocloft 包的加载添加到导言区，还要将 \renewcommandsphinxtableofcontentshook{} 添加到导言区，否则它将重置 \l@section 和 \l@subsection，从而取消 tocloft 自定义。
\sphinxmaketitle: 用作 'maketitle' latex_elements 键的默认设置。在类文件 sphinxmanual.cls 和 sphinxhowto.cls 中定义。

在 1.8.3 版本中变更: 以前，LaTeX 文档类中的 \maketitle 由 Sphinx 修改。
\sphinxbackoftitlepage: 对于 'manual' 文档类，如果已定义，则在 \sphinxmaketitle 结束时、在最终的 \clearpage 之前执行。使用 latex_elements 的 'maketitle' 键或 'preamble' 键来添加 \sphinxbackoftitlepage 的自定义定义。

在 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, background-TeXcolor, box-shadow-TeXcolor, TeXcolor,
TeXextras,
以及 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 结尾。

在 1.5.6 版本中新增: 以前，\small 在 LaTeX 编写器中是硬编码的，并且缺少结尾的 \par。
与提示框关联的环境
- sphinxnote,
- sphinxhint,
- sphinximportant,
- sphinxtip,
- sphinxwarning,
- sphinxcaution,
- sphinxattention,
- sphinxdanger,
- sphinxerror.
它们可以单独使用 \renewenvironment ‘d，然后必须使用一个参数定义（它是通知的标题，例如，对于 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 的包装器）和单独的自定义功能。
文字块（通过 :: 或 code-block）和文字包含（literalinclude）是使用 sphinxVerbatim 环境实现的，该环境是来自包 fancyvrb.sty 的 Verbatim 环境的包装器。它添加了顶部标题的处理和长行的换行，以及允许分页符的框架。在表格内部，使用的环境是 sphinxVerbatimintable （它不绘制框架，但允许标题）。

在 1.5 版本中变更: Verbatim 与 fancyvrb.sty 中的含义完全相同（也以名称 OriginalVerbatim 存在）； sphinxVerbatimintable 在表格内部使用。

在 1.5 版本中新增: 选项 verbatimwithframe、verbatimwrapslines、verbatimsep、verbatimborder。

在 1.6.6 版本中新增: 支持 :emphasize-lines: 选项

在 1.6.6 版本中新增: 通过暴露给用户的 LaTeX 宏（例如 \sphinxVerbatimHighlightLine）更容易自定义格式。
参考书目使用 sphinxthebibliography，Python 模块索引和常规索引都使用 sphinxtheindex；这些环境分别是文档类（或包）提供的 thebibliography 和 theindex 环境的包装器。

在 1.5 版本中变更: 以前，原始环境由 Sphinx 修改。

杂项¶

文档正文中的每个文本段落都以 \sphinxAtStartPar 开头。目前，这用于插入零宽度水平间距，这是一种技巧，允许 TeX 在狭窄的上下文（如表格单元格）中对段落的第一个单词进行断字。对于不需要此技巧的 'lualatex'，\sphinxAtStartPar 不执行任何操作。

在版本 3.5.0 中添加。
节、子节、... 标题是使用 titlesec 的 \titleformat 命令设置的。
对于 'manual' 文档类，章节标题可以使用 fncychap 的命令 \ChNameVar、\ChNumVar、\ChTitleVar 进行自定义。如果 fncychap 选项为 Bjarne，则文件 sphinx.sty 具有自定义的重新定义。

在 1.5 版本中变更: 以前，将 fncychap 与 Bjarne 以外的样式一起使用是功能失调的。
role 指令允许使用类参数标记内联文本。这在 LaTeX 输出中通过 \DUrole 调度器命令处理，如 Docutils 中所述。对象签名也对某些组件使用 \DUrole，类名称为一或两个字母，与 HTML 输出中相同。

在 8.1.0 版本中变更: 当通过自定义角色注入多个类时，LaTeX 输出使用嵌套的 \DUrole，如 Docutils 文档中所述。以前，它使用带有逗号分隔类的单个 \DUrole，这使得 LaTeX 自定义更加困难。

Docutils container 指令在 LaTeX 输出中受支持：要让类名称为 foo 的容器类通过 LaTeX 影响最终 PDF，只需在导言区中定义一个环境 sphinxclassfoo。一个简单的例子是
```
\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）

LaTeX 定制¶

latex_elements 配置设置¶

sphinxsetup 配置设置¶

额外的类 CSS 'sphinxsetup' 键¶

LaTeX 宏和环境¶

宏¶

\sphinxbox 命令¶

环境¶

杂项¶

`latex_elements` 配置设置¶

`sphinxsetup` 配置设置¶

额外的类 CSS `'sphinxsetup'` 键¶

`\sphinxbox` 命令¶