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”包的包含。

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

注意

如果使用 utf8x 代替 utf8，则必须按照 utf8x 文档（在基于 TeXLive 的 TeX 安装上运行 texdoc ucs）的要求，用合适的 \PreloadUnicodePage{<number>} 命令扩展 LaTeX 序言。否则，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'

对于 latex_engine 设置为 'pdflatex'，其默认值为 r'\usepackage[T1]{fontenc}'。如果您需要偶尔的西里尔字母（физика частиц），请将其（如果使用 'pdflatex'）替换为

  • r'\usepackage[X2,T1]{fontenc}'，如果您需要偶尔的西里尔字母（физика частиц），

  • r'\usepackage[LGR,T1]{fontenc}'，如果您需要偶尔的希腊字母（Σωματιδιακή φυσική），

  • r'\usepackage[LGR,X2,T1]{fontenc}'，如果您两者都需要。

TeX 安装可能需要一些额外的软件包。例如，在 Ubuntu xenial 上

  • 希腊语 (LGR) 需要 texlive-lang-greek 和 cm-super，

  • 西里尔语 (X2) 需要 texlive-lang-cyrillic 和 cm-super。

使用 'xelatex' 和 'lualatex'，希腊语和西里尔语的支持是开箱即用的：此 'fontenc' 键默认为包含 LaTeX 包 fontspec（带有一些下面描述的额外内容），并选择 GNU FreeSerif 字体作为正文字体。请参阅 'fontpkg'。

在 1.5 版本中更改：如果 latex_engine 设置为 'xelatex'，则默认为 r'\usepackage{fontspec}'。

在 1.6 版本中更改：如果 latex_engine 设置为 'lualatex'，则默认为 r'\usepackage{fontspec}'。

在 2.0 版本中更改：'lualatex' 额外执行 \defaultfontfeatures[\rmfamily,\sffamily]{} 以禁用 << 和 >> 的 TeX 连字。

在 2.0 版本中更改：如果在此键中检测到 LGR、T2A 或 X2，则会自动执行额外的 LaTeX 配置，以支持使用 'pdflatex' 时偶尔出现的希腊文或西里尔文。

在 2.2.1 版本中更改：主语言为希腊语的文档默认为 'xelatex'，并且不应设置 'fontenc' 键，该键将加载 fontspec。

在 2.3.0 版本中更改：'xelatex' 执行 \defaultfontfeatures[\rmfamily,\sffamily]{} 以避免 -- 收缩为 en-dash，并且还会将直引号转换为弯引号（否则即使 smartquotes 设置为 False 也会发生）。

'fontsubstitution'

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

对于 latex_engine 不是 'pdflatex' 的情况，此项被忽略。

4.0.0 版本新增。

'textgreek'

用于支持偶尔的希腊字母。

如果 latex_engine 设置为 'platex'、'xelatex' 或 'lualatex'，则此项会被忽略，并且默认为空字符串或 r'\usepackage{textalpha}'，具体取决于 'fontenc' 键是否与 LGR 一起使用。<只有专家级 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 版本中更改：如果 latex_engine 是 'platex'，则使用 dvipdfm 选项。

在 1.5.3 版本中新增：边距的“sphinxsetup”键。

在 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' 文档类）。

默认值：r'\sphinxmaketitle'

在 1.8.3 版本中更改：文档类中的原始 \maketitle 不会被覆盖，因此可以作为此键的自定义设置的一部分重复使用。

在 1.8.3 版本中新增：\sphinxbackoftitlepage 可选宏。它也可以在此键中定义，而不是在 'preamble' 键中定义。

'releasename'

在标题页上位于 'release' 元素之前的字符串值。与 latex_documents 元组中使用的 title 和 author 一样，它作为 LaTeX 标记插入。

默认值：'Release'

'tableofcontents'

“tableofcontents”调用。r'\sphinxtableofcontents' 的默认值是未经修改的 \tableofcontents 的包装器，它本身可以通过用户加载的包进行定制。如果您想生成不同的目录或在标题页和目录之间放置内容，请覆盖。

默认值：r'\sphinxtableofcontents'

在 1.5 版本中更改：此前，\tableofcontents 本身的含义被 Sphinx 修改。这导致与修改它的专用包（如“tocloft”或“etoc”）不兼容。

'transition'

用于显示过渡的命令。如果您想以不同的方式显示过渡，请覆盖。

默认值：'\n\n\\bigskip\\hrule\\bigskip\n\n'

版本 1.2 中新增。

在 1.6 版本中更改：移除了之前位于 \hrule 之后不必要的 {}。

'makeindex'

“makeindex”调用，\begin{document} 之前的最后一步。使用 r'\usepackage[columns=1]{idxlayout}\makeindex' 索引将只使用一列。您可能需要安装 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}'，这意味着如果代码块最终出现在脚注中，字体大小将正确调整。当使用自定义等宽字体时，您可能需要修改此项，例如将其设置为 r'\fvset{fontsize=\small}'，如果它是 Courier 类型的（对于 Unicode 引擎，建议使用 \setmonofont LaTeX 命令的 Scale 接口，来自 fontspec）。

默认值：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}',
}
书签深度

控制 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 包会传递合适的选项，使文本宽度设置为 zenkaku 宽度的精确倍数，文本高度设置为基线高度的整数倍，并以最接近的边距进行匹配。

默认值：1in（相当于 {1in,1in}）

提示

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

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

1.5.3 版本新增。

marginpar

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

默认值：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

相对于带框内容的水平位置：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

代码块 的背景颜色。

默认值：{RGB}{242,242,242}（与 {gray}{0.95} 相同）。

在 6.0.0 版本中更改：以前是 {rgb}{1,1,1}（白色）。

VerbatimBorderColor

边框颜色。

默认值：{RGB}{32,32,32}

在 6.0.0 版本中更改：以前是 {rgb}{0,0,0}（黑色）。

VerbatimHighlightColor

高亮行的颜色。

默认值：{rgb}{0.878,1,1}

1.6.6 版本新增。

TableRowColorHeader

设置表格所有表头行的背景颜色。

它仅在 latex_table_style 包含 'colorrows' 或表格被赋予 colorrows 类时才有效。对于带有 nocolorrows 类的表格，它将被忽略。

与其他的 'sphinxsetup' 键一样，它也可以通过 raw 指令插入的 \sphinxsetup{...} LaTeX 命令设置或修改，或者从与 容器类 关联的 LaTeX 环境中使用此类 \sphinxsetup{...} 设置。

默认值：{gray}{0.86}

还有 TableMergeColorHeader。如果使用，则为标题中合并的单行单元格设置特定颜色。

5.3.0 版本新增。

TableRowColorOdd

设置表格中奇数行的背景颜色（行数从第一个非标题行开始计数为 1）。仅当 latex_table_style 包含 'colorrows' 或指定表格被赋予 colorrows 类时才有效。

默认值：{gray}{0.92}

还有 TableMergeColorOdd。

5.3.0 版本新增。

TableRowColorEven

设置表格中偶数行的背景颜色。

默认值 {gray}{0.98}

还有 TableMergeColorEven。

5.3.0 版本新增。

verbatimsep

代码行与边框之间的间距。

请参阅 其他类似 CSS 的“sphinxsetup”键，了解其别名 pre_padding 和其他键。

默认值：\fboxsep

verbatimborder

代码块 周围边框的宽度。另请参阅 其他类似 CSS 的“sphinxsetup”键，了解 pre_border-width。

默认值：\fboxrule

重要

自 8.1.0 版本起，可以单独设置 topic、contents 和 sidebar 指令的样式，并且它们的默认值不同。请参阅 其他类似 CSS 的“sphinxsetup”键。接下来的三个键作为传统接口保留，不区分这三个指令。

shadowsep

此传统选项同时为 主题、目录 和 侧边栏 指令设置填充（所有方向相同）。

shadowsize

此传统选项同时为 主题、目录 和 侧边栏 指令设置阴影宽度。

shadowrule

此传统选项同时为 主题、目录 和 侧边栏 指令设置边框宽度（所有边相同）。

重要

在 7.4.0 版本中，所有告诫（不仅是危险类型）都使用了在 5.1.0 和 6.2.0 版本中添加的功能。所有默认值都已更改。

iconpackage

用于在告诫标题中渲染图标的 LaTeX 包名称。其默认值根据所使用的 LaTeX 安装中是否存在这些名称的包，动态设置为 fontawesome7、fontawesome6、fontawesome5、fontawesome 或 none，优先级递减。每个告诫图标的 LaTeX 代码如果使用 fontawesome{5,6,7} 将使用 \faIcon 命令，如果使用 fontawesome 将使用 \faicon。如果找不到任何“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 版本之前被认为是实验性的。这些选项有别名 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 警告框也可以这样设置样式。对它们使用任何列出的选项都会触发使用比默认值（sphinxheavybox vs sphinxlightbox）更复杂的 LaTeX 代码。设置新的 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 环境

代码块

pre

sphinxVerbatim

字面包含

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 更改： sidebar 的默认值与 topic 不同。

  • <prefix>_box-decoration-break 可以设置为 clone 或 slice，并配置分页符处的行为。从 6.0.0 版开始，对于 code-block（即对于 <prefix>=pre），它默认为 slice。对于其他指令，默认值为 clone。

  • <prefix>_padding-top,
    <prefix>_padding-right,
    <prefix>_padding-bottom,
    <prefix>_padding-left,
    <prefix>_padding。后者（目前）只能是一个单一维度，它将设置所有其他四个维度。

    默认值

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

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

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

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

    • 所有“轻量”警告框以及 seealso 和 todo 指令均为 6pt、7pt、6pt、7pt。

    • 对于强类型警告框，除 error（使用 6.25pt 的水平填充）外，其他均为 6pt、6.5pt、6pt、6.5pt。

    版本 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。最后一个键将其分配的值设置为前四个键。每个键值可以是一个或两个用空格分隔的维度。

    默认值

    • 对于 code-block（自 6.0.0 起）和所有角落，3pt，

    • topic 的所有角为 8pt，

    • contents 的右下角为 12pt，其他角为 0pt，

    • sidebar 的左上角和右下角为 12pt，右上角和左下角为 0pt。

    • 对于 note、hint 和 tip，所有半径均设置为 5pt，

    • 0pt，即所有其他指令的直角。

    版本 7.4.0 更改： topic 和类似 note 的警告框获得了（至少一个）圆角。

    版本 8.1.0 更改： topic、contents 和 sidebar 的独立默认值。

    请参阅上面关于 LaTeX 中空格陷阱的备注。

  • <prefix>_box-shadow 是特殊的，因为它可能是

    • none 关键字，

    • 或单个维度（给出 x-offset 和 y-offset），

    • 或两个维度（用空格分隔），

    • 或两个维度后跟关键字 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：标题的背景颜色。

    重要

    彩色标题行是 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 使用的图标，如果您的 LaTeX 安装中存在 fontawesome5、6 或 7 之一，请在这些键中使用 \faIcon LaTeX 命令。如果您的系统仅提供 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 的相同恒定宽度。

  • 内嵌阴影与圆角不兼容。如果同时指定两者，内嵌阴影将被简单地忽略。

    版本 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'] 将代码添加到序言之外，还可以通过在项目源中包含修改后的副本并将文件名添加到 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：标准 \tableofcontents 的包装器（在 sphinxhowto.cls 和 sphinxmanual.cls 中定义不同）。宏 \sphinxtableofcontentshook 在其展开过程中，紧接在 \tableofcontents 本身之前执行。

    版本 1.5 更改： 以前，\tableofcontents 的含义被 Sphinx 修改了。

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

    提示

    如果在序言中添加了 tocloft 包的加载，也请在序言中添加 \renewcommand\sphinxtableofcontentshook{}，否则它将重置 \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 命令，带有一个可选参数，该参数是一个逗号分隔的键值对列表，与 sphinxsetup 配置设置 类似。以下是完整的键列表。它们不使用任何前缀。

  • 边框宽度,

  • border-top-width、border-right-width、border-bottom-width、border-left-width，

  • 填充,

  • padding-top、padding-right、padding-bottom、padding-left，

  • 边框半径,

  • 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，用于创建一个新的 boxing 宏，例如 \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（来自原始 LaTeX 标记）设置，唯一的区别是它们具有一组初始的额外默认设置。

在上述示例中，您可能可以使用 \renewcommand 语法，如果您更喜欢它而不是 \protected\def（在这种情况下，[1] 代替 #1）。

环境

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

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

  • 与警告相关的环境

    • sphinxnote,

    • sphinxhint,

    • sphinximportant,

    • sphinxtip,

    • sphinxwarning,

    • sphinxcaution,

    • sphinxattention,

    • sphinxdanger,

    • sphinxerror.

    它们可以单独使用 \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、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' docclass，章节标题可以使用 fncychap 的命令 \ChNameVar、\ChNumVar、\ChTitleVar 进行自定义。文件 sphinx.sty 在 fncychap 选项 Bjarne 的情况下有自定义的重新定义。

    版本 1.5 更改： 以前，使用 fncychap 与 Bjarne 以外的样式时功能异常。

  • role 指令允许使用类参数标记行内文本。这在 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）