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'

额外的序言内容。可以将所有需要的宏移动到项目源目录中的某个文件 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” 包的包含。

默认值：r'\usepackage[utf8]{inputenc}'（在使用 pdflatex 时），否则为 ''。

注意

如果使用 utf8x 代替 utf8，则必须使用适当的 \PreloadUnicodePage{<number>} 命令扩展 LaTeX 序言，如 utf8x 文档（在基于 TeXLive 的 TeX 安装中为 texdoc ucs）所示。否则，PDF 中可能会出现意外且可能难以发现的问题（即不会导致构建崩溃），尤其是在超链接方面。

即使采取了这些预防措施，通过 pdflatex 引擎构建的 PDF 可能会崩溃，因为上游 LaTeX 与 utf8x 不完全兼容。例如，在与代码块相关的某些情况下，或者尝试包含文件名包含 Unicode 字符的图像。实际上，从 2015 年开始，上游 LaTeX 与 pdflatex 引擎对 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 上

  • texlive-lang-greek 和 cm-super 是希腊语（LGR）所必需的，

  • texlive-lang-cyrillic 和 cm-super 是西里尔语（X2）所必需的。

使用 '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]{} 为了避免将 -- 缩写为连接号，以及避免将直引号转换为弯引号（否则即使将 smartquotes 设置为 False 也会发生这种情况）。

'fontsubstitution'

如果 'fontenc' 未配置为使用 LGR 或 X2（或 T2A），则会被忽略。如果 'fontpkg' 键被配置为与已知在 LGR 或 X2 编码中可用的某些 TeX 字体一起使用，则将此键设置为为空字符串。否则将其保留为默认值。

对于除 'pdflatex' 之外的 latex_engine，会被忽略。

在版本 4.0.0 中添加。

'textgreek'

用于偶尔支持希腊字母。

在 'platex'、'xelatex' 或 'lualatex' 作为 latex_engine 时会被忽略，并且默认值为 '' 或 r'\usepackage{textalpha}'（对于 'pdflatex'），具体取决于是否使用 LGR 使用了 'fontenc' 键。只有专家 LaTeX 用户可能希望自定义此键。

它也可以用作 r'\usepackage{textalpha,alphabeta}'，以使 'pdflatex' 支持 math 上下文中的希腊语 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 中已更改: dvipdfm 选项，如果 latex_engine 为 'platex'。

版本 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 的包装器，它本身可能由用户加载的包自定义。如果您想生成不同的目录或将内容放在标题页和目录之间，请覆盖此项。

默认值：r'\sphinxtableofcontents'

版本 1.5 中已更改: 以前，Sphinx 会修改 \tableofcontents 本身的含义。这会导致与专门用于修改它的包（例如“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'（如果使用自定义文档类，此技巧可能会失败；然后尝试 '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'，默认为 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

水平（分别为垂直）边距的尺寸，作为 hmargin（分别为 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“真”单位。

'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'，则只允许 Unicode 代码点的默认 LaTeX 处理，即 utf8 而不是 utf8x。

默认：false

在版本 3.5.0 中添加。

verbatimmaxoverfull

一个数字。如果不可拆分的长字符串的长度大于总行宽加上此数字的字符数，并且如果 verbatimforcewraps 模式处于开启状态，则输入行将使用强制算法重置，该算法在每个字符处应用断点。

默认：3

在版本 3.5.0 中添加。

verbatimmaxunderfull

一个数字。如果 verbatimforcewraps 模式应用，并且在空格和标点符号处应用换行后，拆分行的第一部分缺少至少此数字的字符来填充可用宽度，则输入行将使用强制算法重置。

由于默认值设置为较高的值，因此强制算法仅在 overfull 情况下触发，即在存在长于完整行宽的字符串的情况下。将其设置为 0 以强制所有输入行在当前可用行宽处强制换行。

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

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

默认：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} 或…

  • 或遵守 \colorlet 命令的语法，该命令来自 “xcolor” 包，例如 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' 键，也可以通过 \sphinxsetup{...} LaTeX 命令从 raw 指令插入，或者从与 容器类 关联的 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' 键。接下来的三个键作为传统接口保留，不区分这三个指令。

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，这意味着不会尝试加载任何包。独立于此设置，可以通过 div.<type>_icon-title 键将任意 LaTeX 代码与每个警示类型关联，这些键在 其他类似 CSS 的 'sphinxsetup' 键 部分中进行了描述。如果未使用这些键，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 之前被认为是实验性的。这些选项有别名 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。

版本 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.cn 上呈现的 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 等值的可以是一个或两个空格分隔的维度。

  • 尺寸规范必须使用 TeX 单位，例如 pt 或 cm 或 in。 px 单位被 pdflatex 和 lualatex 识别，但没有被 xelatex 或 platex 识别。

  • 允许此类规范为所谓的“尺寸表达式”，例如 \fboxsep+2pt 或 0.5\baselineskip 是有效的输入。这些表达式仅在排版时进行计算。但是，如果使用像这些示例中的 TeX 控制序列，请注意对反斜杠进行双重转义或使用原始 Python 字符串作为 ‘sphinxsetup’ 键的值。

  • 通常，避免在键值中插入不必要的空格：特别是对于半径，输入 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。后者（目前）只能是单个维度，然后设置所有四个维度。

    默认情况下，所有这些维度都相等。它们设置为

    在版本 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。后者（目前）只能是单个维度，然后设置所有四个维度。

    默认值

    • 所有四个都为 3pt 对于 code-block,

    • 6pt、7pt、6pt、7pt 对于 topic,

    • 10pt、7pt、12pt、7pt 对于 contents,

    • 6pt、5.5pt、6pt、5.5pt 对于 sidebar,

    • 6pt, 7pt, 6pt, 7pt 用于所有“light”类型的警示以及 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' 键向 xcolor 传递选项，例如 dvipsnames， svgnames 或 x11names。

    如果设置了 <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 包，构建过程将继续进行，并且会将所有框渲染成直角。

  • 椭圆形角使用 ellipse LaTeX 包，该包扩展了 pict2e。如果找不到这个 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] 括号更大，请查看源代码

    版本 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: 主题、目录 和 侧边栏 指令的标题也使用 \sphinxdotitlerow 进行样式设置（它们没有关联的默认图标）。

  • \sphinxtableofcontents：标准 \tableofcontents 的包装器（在 sphinxhowto.cls 和 sphinxmanual.cls 中定义不同）。宏 \sphinxtableofcontentshook 在 \tableofcontents 本身扩展之前，在其扩展期间执行。

    更改于版本 1.5: 以前，Sphinx 会修改 \tableofcontents 的含义。

    更改于版本 2.0: 以前在加载 'manual' 文档类时进行的 \l@section 和 \l@subsection 的硬编码重新定义现在通过 \sphinxtableofcontentshook 在之后执行。此宏也由 'howto' 文档类执行，但默认情况下它为空。

    提示

    如果在序言中添加加载 tocloft 包，还要在序言中添加 \renewcommandsphinxtableofcontentshook{}，否则它将重置 \l@section 和 \l@subsection，从而取消 tocloft 的自定义。

  • \sphinxmaketitle：用作 latex_elements 键的默认设置。在类文件 sphinxmanual.cls 和 sphinxhowto.cls 中定义。

    更改于版本 1.8.3: 以前，Sphinx 会修改来自 LaTeX 文档类的 \maketitle。

  • \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 命令，带有一个可选参数，即一个逗号分隔的键值对列表，与 “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（然后在 [1] 的位置使用 #1）。

环境

  • 一个 图表 可以有一个可选的图例，其中包含任意正文元素：它们在一个 sphinxlegend 环境中呈现。默认定义会发出 \small，并在最后用 \par 结束。

    在版本 1.5.6 中添加: 以前，\small 在 LaTeX 编写器中是硬编码的，而最后的 \par 则缺失。

  • 与注意事项相关的环境

    • sphinxnote,

    • sphinxhint,

    • sphinximportant,

    • sphinxtip,

    • sphinxwarning,

    • sphinxcaution,

    • sphinxattention,

    • sphinxdanger,

    • sphinxerror.

    它们可以被 \renewenvironment ‘d 个别地重新定义，并且必须用一个参数来定义（例如，对于 警告 指令，如果文档语言是英文，则该参数是通知的标题，例如 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 中新增。

  • 主题、目录和侧边栏指令分别与 sphinxtopic、sphinxcontents 和 sphinxsidebar 环境相关联。

    在版本 1.4.2 中添加: 以前的代码重构为一个允许分页的环境。

    在版本 1.5 中更改: 选项 shadowsep、shadowsize、shadowrule。

    在版本 8.1.0 中添加: 独立的环境（所有 3 个包装器都围绕着 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。文件 sphinx.sty 在 fncychap 选项 Bjarne 的情况下有自定义的重新定义。

    在版本 1.5 中更改: 以前，使用 fncychap 除了 Bjarne 之外的其他样式会导致功能失常。

  • 角色指令允许使用类参数标记内联文本。在 LaTeX 输出中，这通过 \DUrole 调度程序命令处理 如 Docutils 中一样。对象签名也使用 \DUrole 来处理某些组件，使用 HTML 输出中的一个或两个字母的类名。

    在版本 8.1.0 中更改: 当通过自定义角色注入多个类时，LaTeX 输出使用嵌套的 \DUrole，如 Docutils 文档 中一样。以前它使用单个 \DUrole，其中类名用逗号分隔，这使得 LaTeX 自定义更加繁琐。

  • Docutils 的 容器 指令在 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)