LaTeX个性化

latex 构建器无法使用html构建器专用的 HTML主题。用于LaTeX输出的选项，尤其是 latex_elements 变量，为定制latex页面提供了许多接口。例如：

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

document类的纸张大小选项（'a4paper' 或 'letterpaper'）

默认：'letterpaper'

'pointsize'

document类的字号大小选项（'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）。对于日语文档，默认值为空字符串。

在Xeletex和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 项目源代码库，并在运行时将其导入：

'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 extensions加载包之前加载。

提示

如果您想在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，则必须使用适当的 \PreloadUnicodePage{<number>} 命令扩展LaTeX前导码，如 utf8x 文档所示（在基于TeXLive的TeX安装上使用 texdoc ucs）。否则，PDF中可能会出现意外且可能难以发现的问题（即不会导致构建崩溃），尤其是关于超链接的问题。

即使采取了这些预防措施，通过 pdflatex 引擎进行的PDF构建也可能会由于上游LaTeX与 utf8x 不完全兼容而崩溃。例如，在与代码块相关的某些情况下，或者尝试包含文件名包含Unicode字符的图像时。事实上，从2015年开始，使用 pdflatex 引擎的上游LaTeX已经增强了对Unicode的本机支持，并且与 utf8x 越来越不兼容。特别是，自2019年10月的LaTeX版本以来，文件名可以使用Unicode字符，甚至空格。在Sphinx级别，这意味着例如 image 和 figure 指令现在与通过LaTeX输出的PDF兼容此类文件名。但如果使用 utf8x，则会出现问题。

在 1.4.3 版本发生变更: 以前，r'\usepackage[utf8]{inputenc}' 用于所有编译器。

'cmappkg'

包含“cmap”软件包。

默认值： r'\usepackage{cmap}'

在 1.2 版本加入.

'fontenc'

对于 '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]{} 以避免将 -- 收缩为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 时被忽略，并且取决于是否在 'fontenc' 键中使用了 LGR，对于 'pdflatex'，默认为空字符串或 r'\usepackage{textalpha}'。只有专业的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 版本发生变更: dvipdfm 选项 如果 latex_engine 是 'platex'.

在 1.5.3 版本加入: 'sphinxsetup' keys for the margins。

在 1.5.3 版本发生变更: LaTeX文件中的位置已移动到 \usepackage{sphinx} 和 \sphinxsetup{..} 之后，因此也在插入 'fontpkg' 键之后。这是为了以特殊方式处理日语文档的纸张布局选项：文本宽度将设置为*zenkaku*宽度的整数倍，文本高度将设置为基线的整数倍。有关更多信息，请参见 hmargin 文档。

'hyperref'

包含“hyperref”包；还加载包“hypcap”并发出 \urlstyle{same}。这是在加载 sphinx.sty 文件之后以及执行 'preamble' 键的内容之前完成的。

注意

必须加载“hyperref”和“hypcap”包。

在 1.5 版本加入: 以前这是从内部完成的：文件：sphinx.sty.

'maketitle'

“maketitle”调用。如果要生成不同样式的标题页，请重写。

提示

如果键值设置为 r'\newcommand\sphinxbackoftitlepage{<Extra material>}\sphinxmaketitle'，则 <Extra material> 将在标题页背面排版（仅限 'manual' docclass）。

默认值: r'\sphinxmaketitle'

在 1.8.3 版本发生变更: 文档类的原始 \maketitle 未被覆盖，因此可以作为此键的一部分重用。

在 1.8.3 版本加入: \sphinxbackoftitlepage 可选宏。它也可以在 'preamble' 键内定义，而不是这个键。

'releasename'

在标题页上以“release”元素为前缀的值。至于 title 和 author 在 latex_documents 的元组中使用，它是作为latex标记插入的。

默认值: 'Release'

'tableofcontents'

“tableofcontents”调用。 r'\sphinxtableofcontents' 的默认值是未修改的 \tableofcontents 的包装器，用户加载的软件包本身可以自定义它。如果要生成不同的目录或在标题页和TOC之间放置内容，请重写。

默认值: 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 接口）。

Default: 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输出特别设计文档当前部分的技术。实际上使用的选项将在 development repository 的 doc/latex.rst 顶部找到。

上面示例中使用的颜色可通过向“xcolor”包传递 svgnames 选项获得：：

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

控制PDF中可折叠书签面板的深度。可以是数字（例如 3）或LaTeX分节名称（例如 subsubsection，即没有反斜杠）。

默认: 5

在 4.0.0 版本加入.

hmargin, vmargin

水平（或垂直）方向的尺寸页边距，作为 hmargin 传递（或 vmargin）给 geometry 包的选项。例子:

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

日语文档目前只接受这些参数的一维格式。然后向 geometry 包传递适当的选项，使文本宽度设置为 zenkaku 宽度的精确倍数，文本高度设置为基准线的整数倍，并与边距最接近。

默认值: 1in (equivalent to {1in,1in})

提示

对于点大小为11pt或12pt的日文“manual”docclass，使用“nomag”额外的文档类选项（参见 latex_elements）的“extraclassoptions”键或所谓的TeX“true”单位：

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

在 1.5.3 版本加入.

marginpar

\marginparwidth LaTeX 维度。对于日语文档，该值被修改为 zenkaku 宽度的最接近整数倍。

默认值: 0.5in

在 1.5.3 版本加入.

mathnumsep

这默认为 math_numsep 设置的字符串（不带引号！）（它本身默认为 '.'）。如果LaTeX输出需要不同的设置，请使用它。

在 8.1.0 版本加入.

literalblockcappos

决定标题位置：要么是 b (底部)，要么是 t (顶部)。

默认值： t

在 1.7 版本加入.

verbatimwithframe

布尔值指定是否对 code-blocks 和文字包含进行框架设置。将其设置为 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指令在latex文件中插入适当的 \sphinxsetup （之前和之后）来为给定的代码块局部完成。

默认：100

在 3.5.0 版本加入.

verbatimhintsturnover

布尔值指定代码块在分页时是否显示“继续下一页”和“从上一页继续”提示。

默认值: true

在 1.6.3 版本加入.

在 1.7 版本发生变更: 默认值从 false 更改为 true。

verbatimcontinuedalign, verbatimcontinuesalign

相对于框架内容的水平位置： l （左对齐）、r （右对齐）或 c （居中）。

默认值: r

在 1.7 版本加入.

parsedliteralwraps

Boolean指定 parsed-literal 内容中的长行是否应换行。

默认值: true

在 1.5.2 版本加入: 将此选项值设置为 false 以恢复以前的行为。

inlineliteralwraps

Boolean指定是否允许在内联文字中使用换行符：但当前仅在字符 . , ; ? ! / 之后插入额外的潜在断点（除了LaTeX允许的空格或连字号）和 \ 。由于TeX内部结构，行中的空白将被拉伸（或收缩）以适应linebreak。

默认值: 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中更改，以适应各种字体大小（例如，代码块可以在脚注中）。

备注

颜色keys的值必须是：

  • 遵守 \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-blocks 的背景颜色。

默认值: {RGB}{242,242,242} (same as {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命令进行设置或修改，或者也可以从与 container class 相关联的LaTeX环境中使用此类 \sphinxsetup{...}。

默认：{gray}{0.86}

There is also 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-blocks 周围框架的宽度。另请参阅 额外的类似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中，所有警告（不仅仅是危险类型）都使用了在5.1.0和6.2.0中添加的功能。所有默认值都已更改。

iconpackage

用于在警告标题中呈现图标的LaTeX包的名称。它的默认值动态设置为 fontawesome7、fontawesome6、fontawesome5、fontawesome 或 none，按优先级递减顺序，并取决于所使用的LaTeX安装中是否存在这些名称的包。每个警告图标的LaTeX代码将使用 \faIcon 命令（如果使用 fontawesome{5,6,7}）和 \faicon （如果使用 fontawesome）。如果未找到任何“Font Awesome”相关包（或者如果选项被强制设置为 none），则图标将被静默丢弃。用户可以将此选项设置为某个特定包，然后必须配置 div.note_title-icon 和类似的键以使用该LaTeX包接口（请参阅关于此的 额外的类似CSS的 'sphinxsetup' 键 部分）。

在 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 版本发生变更.

起始脚注

LaTeX宏插入页面底部脚注文本的开头，脚注编号之后。

默认值: \mbox{ }

脚注之前

在脚注标记之前插入的乳胶宏。默认值会删除其前面可能的空格（否则，TeX可以在那里插入一个换行符）。

默认值: \leavevmode\unskip

在 1.5 版本加入.

头家

默认值 \sffamily\bfseries。设置标题使用的字体。

额外的类似CSS的 'sphinxsetup' 键

在 5.1.0 版本加入: For code-block、topic 和 contents 指令，以及强类型警告（warning、error，...）。

在 6.2.0 版本加入: 同样，note、hint、important 和 tip 警告也可以这样设置样式。为它们使用*任何*列出的选项都将触发使用比默认使用的更复杂的LaTeX代码（sphinxheavybox vs sphinxlightbox）。为 note`（或 :dudir:`hint，...）设置新的 noteBgColor （或 hintBgColor，...）也会触发使用 sphinxheavybox。

在 7.4.0 版本加入: 对于 所有的 警告类型，默认配置确实设置了背景颜色（因此总是使用更丰富的 sphinxheavybox）。

重要

此外，所有警告标题默认都使用彩色行和图标进行样式设置，这些样式基于Sphinx自己文档在 https://www.sphinx-doc.org 上的当前渲染。添加了类似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。后者目前只能是一个 单一 维度，然后设置其他四个。

    默认情况下，所有这些尺寸都是相等的。它们被设置为：

    在 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 用于强警告类型，除了使用水平填充 6.25pt 的 error。

    在 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 类型警告的边框颜色，除了使用 {HTML}{B40000} 的 error。

    默认情况下，唯一显示阴影的指令是 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：标题的背景颜色。

    重要

    彩色标题行是Sphinx对各种 \sphinxstyle<type>title 命令的默认定义的结果，它们使用 \sphinxdotitlerow LaTeX 命令。请参阅 宏。

  • div.<type>_title-foreground-TeXcolor：用于图标的颜色（仅适用于图标，不适用于警告的标题）。

  • div.<type>_title-icon：负责为给定的 <admonition type> 生成图标的LaTeX代码。例如，对于 note 的默认值是 div.note_title-icon=\faIcon{info-circle} 使用 fontawesome5，但使用 fontawesome6 和 fontawesome7 时为 div.note_title-icon=\faIcon{circle-info}。如果您想修改Sphinx使用的图标，请在这些键中使用 \faIcon LaTeX命令，如果您的LaTeX安装中有 fontawesome5、6 或 7 之一。如果您的系统仅提供 fontawesome 包，请使用其命令 \faicon （不是 \faIcon）来修改图标的选择。 'sphinxsetup' 的 iconpackage 键可用于强制使用 fontawesome{,5,6,7} 之一，或是某个其他提供图标的包的名称。在后一种情况下，您必须配置 div.<type>_title-icon 键以使用适合该自定义图标包的LaTeX命令。

备注

  • 所有指令都支持将 box-decoration-break 设置为 slice。

    在 6.2.0 版本发生变更: 以前，只有 code-block 支持。对于所有其他指令，默认值仍然是 clone，但这可能会在7.0.0中更改。

  • 圆角盒子的角可以是椭圆形的。

    在 6.2.0 版本发生变更: 以前，只支持圆形圆角，圆角强制整个框架使用来自 <prefix>_border-width 的相同恒定宽度。

  • Inset阴影与圆角不兼容。如果两者都被指定，则会忽略inset阴影。

    在 6.2.0 版本发生变更: 以前情况正好相反，如果指定了inset阴影，则会忽略圆角。

  • <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'] 向前言添加代码外，还可以通过在项目源中包含修改后的副本并将文件名添加到 latex_additional_files 列表中，完全用自定义版本替换Sphinx LaTeX代码的组件文件之一。检查LaTeX构建目录以获取文件名和内容。

在 4.0.0 版本发生变更: 将 sphinx.sty 拆分为多个较小的单元，以便同时定制多个方面。

宏

  • 文本样式命令：

    名称， 映射参数#1到：

    \sphinxstrong

    \textbf{#1}

    \sphinxcode

    \texttt{#1}

    \sphinxbfcode

    \textbf{\sphinxcode{#1}}

    \sphinxemail

    \textsf{#1}

    \sphinxtablecontinued

    \textsf{#1}

    \sphinxtitleref

    \emph{#1}

    \sphinxmenuselection

    \emph{#1}

    \sphinxguilabel

    \emph{#1}

    \sphinxkeyboard

    \sphinxcode{#1}

    \sphinxaccelerator

    \underline{#1}

    \sphinxcrossref

    \emph{#1}

    \sphinxtermref

    \emph{#1}

    \sphinxsamedocref

    \emph{#1}

    \sphinxparam

    \emph{#1}

    \sphinxtypeparam

    \emph{#1}

    \sphinxoptional

    [#1] 带有更大的括号，见源码

    在 1.4.5 版本加入: 使用前缀为“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} 来更改它。

  • 更多文本样式：

    名称， 映射参数#1到：

    \sphinxstyleindexentry

    \texttt{#1}

    \sphinxstyleindexextra

    (\emph{#1}) （前面有一个空格）

    \sphinxstyleindexpageref

    , \pageref{#1}

    \sphinxstyleindexpagemain

    \textbf{#1}

    \sphinxstyleindexlettergroup

    {\Large\sffamily#1}\nopagebreak\vspace{1mm}

    \sphinxstyleindexlettergroupDefault

    请看源码，太长写不下

    \sphinxstyletopictitle

    \textbf{#1}\par\medskip

    \sphinxstylesidebartitle

    \textbf{#1}\par\medskip

    \sphinxstyleothertitle

    \textbf{#1}

    \sphinxstylesidebarsubtitle

    ~\\\textbf{#1} \smallskip

    \sphinxstyletheadfamily

    \sffamily （它没有参数）

    \sphinxstyleemphasis

    \emph{#1}

    \sphinxstyleliteralemphasis

    \emph{\sphinxcode{#1}}

    \sphinxstylestrong

    \textbf{#1}

    \sphinxstyleliteralstrong

    \sphinxbfcode{#1}

    \sphinxstyleabbreviation

    \textsc{#1}

    \sphinxstyleliteralintitle

    \sphinxcode{#1}

    \sphinxstylecodecontinued

    {\footnotesize(#1)}}

    \sphinxstylecodecontinues

    {\footnotesize(#1)}}

    \sphinxstylenotetitle

    \sphinxdotitlerow{note}{#1}

    \sphinxstylehinttitle

    \sphinxdotitlerow{hint}{#1}

    \sphinxstyleimportanttitle

    \sphinxdotitlerow{important}{#1}

    \sphinxstyletiptitle

    \sphinxdotitlerow{tip}{#1}

    \sphinxstylewarningtitle

    \sphinxdotitlerow{warning}{#1}

    \sphinxstylecautiontitle

    \sphinxdotitlerow{caution}{#1}

    \sphinxstyleattentiontitle

    \sphinxdotitlerow{attention}{#1}

    \sphinxstyledangertitle

    \sphinxdotitlerow{danger}{#1}

    \sphinxstyleerrortitle

    \sphinxdotitlerow{error}{#1}

    \sphinxstyleseealsotitle

    \sphinxdotitlerow{seealso}{#1}

    \sphinxstyletodotitle

    \sphinxdotitlerow{todo}{#1}

    \sphinxstyletopictitle

    \sphinxdotitlerow{topic}{#1}

    \sphinxstylecontentstitle

    \sphinxdotitlerow{contents}{#1}

    \sphinxstylesidebartitle

    \sphinxdotitlerow{sidebar}{#1}

    备注

    为了让此表格适合PDF输出的页面宽度，我们有点撒谎。例如， \sphinxstylenotetitle 的实际定义是：

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

    同样的评论也适用于与警告相关的所有其他类似命令。 topic、contents 和 sidebar 不使用 \sphinxremovefinalcolon，因为它们不需要它。

    在 1.5 版本加入: 这些宏以前被硬编码为不可定制的 \texttt、 \emph 等等。

    在 1.6 版本加入: \sphinxstyletheadfamily，默认值为 \sffamily，允许表格的标题单元格中有多个段落。

    在 1.6.3 版本加入: \sphinxstylecodecontinued 和 \sphinxstylecodecontinues。

    在 1.8 版本加入: \sphinxstyleindexlettergroup， \sphinxstyleindexlettergroupDefault。

    在 6.2.0 版本加入: \sphinxstylenotetitle 等等。 #1 是指令的本地化名称，带有结尾的冒号。如果要删除此结尾的冒号，请将其包装为 \sphinxremovefinalcolon{#1}。

    在 7.4.0 版本加入: 添加了 \sphinxdotitlerowwithicon LaTeX 命令。

    在 8.1.0 版本发生变更: \sphinxdotitlerowwithicon 现在可以自动检测是否有与用作第一个参数的渲染元素相关联的图标。

    在 8.1.0 版本加入: 将 \sphinxdotitlerow 设为 \sphinxdotitlerowwithicon 的别名。

    在 8.1.0 版本加入: topic、contents 和 sidebar 指令的标题也使用 \sphinxdotitlerow 进行样式设置（它们没有与之关联的默认图标）。

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

    在 1.5 版本发生变更: 以前，Sphinx修改了 \tableofcontents 的含义。

    在 2.0 版本发生变更: 以前在加载“manual”文档类时对 \l@section 和 \l@subsection 进行的硬编码重新定义现在通过 \sphinxtableofcontentshook 稍后执行。该宏也由“howto”文档类执行，但默认情况下为空。

    提示

    如果向前言添加 tocloft 包的加载，还要将 \renewcommand\sphinxtableofcontentshook{} 添加到前言，否则它将重置 \l@section 和 \l@subsection，取消 tocloft 的自定义。

  • \sphinxmaketitle：用作 latex_elements 键的 'maketitle' 的默认设置。在类文件 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）。

环境

  • 一个 figure 可以有一个可选的图例，带有任意主体元素：它们在 sphinxlegend 环境中呈现。默认定义发出 \small，并以 \par 结尾。

    在 1.5.6 版本加入: 以前， \small 在 LaTeX 编写器中是硬编码的，并且缺少结尾的 \par。

  • 与环境相关的警告：

    • sphinx批注,

    • sphinx提示,

    • sphinx重点,

    • sphinxt贴士,

    • sphinx警告,

    • sphinx小心,

    • sphinx注意,

    • sphinx危险,

    • sphinx错误.

    它们可以单独使用 \renewenvironment 定义，然后必须使用一个参数进行定义（这是通知的标题，例如，如果英语是文档语言，则为 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, hadowrule 选项。

    在 8.1.0 版本加入: 单独的环境（所有三个都围绕 sphinxShadowBox）和单独的可定制性。

  • 文字块（通过 :: 或 code-block）和文字包含（literalinclude）是使用 sphinxVerbatim 环境实现的，它是包 fancyvrb.sty 中 Verbatim 环境的包装器。它添加了顶部标题和长行换行的处理，以及允许分页符的框架。在表格内使用的环境是 sphinxVerbatimintable （它不绘制框架，但允许标题）。

    在 1.5 版本发生变更: Verbatim 的意思保持一致于在 fancyvrb.sty 中（也在名称 OriginalVerbatim 下）； sphinxverbatimitable 在表中使用。

    在 1.5 版本加入: 选项 verbatimwithframe， verbatimwrapslines， verbatimsep， verbatimborder。

    在 1.6.6 版本加入: 支持 :emphasize-lines: 选项

    在 1.6.6 版本加入: 通过向用户公开的 LaTeX 宏（如 \sphinxVerbatimHighlightLine）更容易自定义格式。

  • 书目使用 sphinxthebibliography，Python模块索引和通用索引都使用 sphinxtheindex；这些环境是文档类（或包）提供的“The书目”和“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 以外的其他样式一起使用是不起作用的。

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

    在 8.1.0 版本发生变更: 当通过自定义角色注入多个类时，LaTeX 输出使用嵌套的 \DUrole，如 Docutils documentation 所示。以前，它使用单个 \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）