Latex 定制

不像 the HTML builders , the latex 构建器不会从准备好的主题中受益。这个 LaTeX输出选项 ，尤其是 latex_elements 变量，为自定义提供了许多接口。例如：

# inside conf.py
latex_engine = 'xelatex'
latex_elements = {
    '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}
''',
    'fncychap': r'\usepackage[Bjornstrup]{fncychap}',
    'printindex': r'\footnotesize\raggedright\printindex',
}
latex_show_urls = 'footnote'

备注

请记住，在Python字符串文本中，反斜杠必须加倍，以避免解释为转义序列。或者，也可以像上面那样使用原始字符串。

这个 latex_elements 配置设置

包含LaTeX代码段的词典会覆盖那些Sphinx通常放入生成的 .tex 档案。它的 'sphinxsetup' 描述了关键字 separately 。它还允许通过以下方式在生成的文件中插入本地配置 raw 指令。例如，在PDF文档中，这一章的样式是特别的，稍后将对此进行描述。

您可能要重写的键包括：

'papersize'

文档类的纸张大小选项 ('a4paper' 或 'letterpaper' ）

违约： 'letterpaper'

'pointsize'

文档类的点大小选项 ('10pt' ， '11pt' 或 '12pt' ）

违约： '10pt'

'pxunit'

的值 px 在图像属性中使用时 width 和 height . 默认值为 '0.75bp' 达到 96px=1in （特克斯） 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”包包含，默认 '\\usepackage{{babel}}' （适当的文档语言字符串作为类选项传递，并且 english 如果没有语言，则使用。）对于日语文档，默认值为空字符串。

使用Xeletex和LuaLaTex，Sphinx将LaTex文档配置为使用 polyglossia 但是我们应该意识到 babel 近年来，它已经改进了对Unicode引擎的支持，对于某些语言，它可能更倾向于使用 babel 结束 polyglossia .

提示

在修改了像这样的核心LaTeX密钥之后，在下一次PDF构建之前清理LaTeX构建库，否则剩余的辅助文件可能会破坏构建。

Default: '\\usepackage{babel}' ('' for Japanese documents)

在 1.5 版本发生变更: 为了 latex_engine 设置为 'xelatex' ，默认为 '\\usepackage{{polyglossia}}\n\\setmainlanguage{{<language>}}' .

在 1.6 版本发生变更: 'lualatex' uses same default setting as 'xelatex'

在 1.7.6 版本发生变更: 法语， xelatex 和 lualatex 默认使用 babel 不是 polyglossia .

'fontpkg'

字体包包含。默认设置为：：

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

为 'xelatex' 和 'lualatex' 但是，默认情况下使用GNU FreeFont。

在 1.2 版本发生变更: 默认为 '' 当 language 使用西里尔文脚本。

在 2.0 版本发生变更: 合并了一些字体替换命令，以帮助支持文档中偶尔使用的希腊文或西里尔文 'pdflatex' 引擎。

在 4.0.0 版本发生变更:

  • 在添加的字体替换命令 2.0 已被转移到 'fontsubstitution' 键，因为它们在此处的存在使用户很难自定义 'fontpkg' 。

  • 默认字体设置已经改变：它仍然将Times和Helvetica克隆用于serif和sans serif，但通过更好、更完整的Tex字体和相关的LaTeX包。等宽字体已被更改，以更好地与泰晤士报的克隆相匹配。

'fncychap'

包含“FNCychap”包（使章节标题花哨），默认 '\\usepackage[Bjarne]{{fncychap}}' 对于英文文档（此选项由Sphinx稍微定制） '\\usepackage[Sonny]{{fncychap}}' 对于国际化文档（因为“bjarne”样式使用英文拼写的数字）。你可以尝试的其他“FNCychap”风格有“Lenny”、“Glenn”、“Conny”、“Reyne”和“Bjornstrup”。您也可以将此设置为 '' 禁用FNCychap。

默认值： '\\usepackage[Bjarne]{{fncychap}}' 对于英文文档， '\\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”包包含。

默认： '\\usepackage[utf8]{inputenc}' 在使用PDF时，否则 '' 。

备注

如果使用 utf8x 代替 utf8 必须用适当的方式延长LaTeX前导码 \PreloadUnicodePage{<number>} 命令，根据 utf8x 文件 (texdoc ucs 在基于TeXLive的TeX安装上)。否则，PDF中可能会出现意想不到的、可能很难发现的问题(即不会导致构建崩溃)，特别是在超链接方面。

即使采取了这些预防措施，PDF也可以通过 pdflatex 上游胶乳与不完全兼容可能导致引擎崩溃 utf8x 。例如，在与代码块相关的某些情况下，或者试图包括其文件名包含Unicode字符的图像。事实上，从2015年开始，上游的 Latex pdflatex Engine在某种程度上增强了对Unicode的本机支持，并且与 utf8x 。特别是，自2019年10月LaTeX发布以来，文件名可以使用Unicode字符，甚至可以使用空格。在Sphinx级别，这意味着 image 和 figure 指令现在通过LaTeX输出与PDF的此类文件名兼容。但如果出现以下情况，这就是错误的 utf8x 正在使用中。

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

'cmappkg'

“cmap”包裹。

违约： '\\usepackage{{cmap}}'

在 1.2 版本加入.

'fontenc'

根据其默认设置对其进行自定义 '\\usepackage[T1]{fontenc}' 致：

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

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

使用 [LGR,X2,T1] 相反，如果两者都需要的话。

注意

  • 请勿将此密钥用于 latex_engine 除 'pdflatex' 。

  • 如果希腊语是主要语言，请不要使用此键。从Sphinx 2.2.1开始， xelatex 将自动用作 latex_engine 。

  • TeX安装可能需要一些额外的程序包。例如，在Ubuntu Xenial上，包 texlive-lang-greek 和 cm-super 是需要的 LGR 去工作。和 texlive-lang-cyrillic 和 cm-super 是支持西里尔语所需要的。

在 1.5 版本发生变更: 默认为 '\\usepackage{{fontspec}}' 什么时候？ latex_engine 是 'xelatex' .

在 1.6 版本发生变更: 'lualatex' 使用 fontspec 按默认类似 'xelatex' .

在 2.0 版本发生变更: 'lualatex' 执行 \defaultfontfeatures[\rmfamily,\sffamily]{{}} 禁用TeX连字转换 << 和 >> 作为逃避工作 pdflatex/xelatex 失败于 lualatex .

在 2.0 版本发生变更: 检测 LGR ， T2A ， X2 触发偶尔支持希腊文或西里尔文字母 ('pdflatex' )。

在 2.3.0 版本发生变更: 'xelatex' 执行 \defaultfontfeatures[\rmfamily,\sffamily]{} 为了避免宫缩， -- 转换为短划线或将直引号转换为PDF中的卷曲引号(在非文字文本段落中)，尽管 smartquotes 被设置为 False 。

'fontsubstitution'

在以下情况下忽略 'fontenc' 未配置为使用 LGR 或 X2 (或 T2A )。万一 'fontpkg' 键配置为使用某些已知可在中使用的TeX字体 LGR 或 X2 编码，则将此值设置为空字符串。否则，保留其默认设置。

忽略，并使用 latex_engine 除 'pdflatex' 。

在 4.0.0 版本加入.

'textgreek'

以获得偶尔的希腊字母的支持。

它将被忽略， 'platex' ， 'xelatex' 或 'lualatex' AS latex_engine 并默认为空字符串或 '\\usepackage{textalpha}' 为 'pdflatex' 这取决于是否 'fontenc' 密钥与一起使用 LGR 或者不去。只有专业的LaTeX用户可能想要自定义此密钥。

它还可以用作 r'\usepackage{textalpha,alphabeta}' 出租 'pdflatex' 支持中的希腊Unicode输入 math 背景。例如 :math:`α (U+03B1)将呈现为 :math:alpha` 。

默认值： '\\usepackage{{textalpha}}' 或 '' 如果 fontenc 不包括 LGR 选项。

在 2.0 版本加入.

'geometry'

“几何”包包含，默认定义为：

'\\usepackage{geometry}'

加上一个 [dvipdfm] 日本文件。Sphinx Latex 样式文件执行：

\PassOptionsToPackage{hmargin=1in,vmargin=1in,marginpar=0.5in}{geometry}

可通过相应的 'sphinxsetup' options .

默认值： '\\usepackage{{geometry}}' (或 '\\usepackage[dvipdfm]{{geometry}}' (适用于日文文档)

在 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' 关键。这是为了以一种特殊的方式处理日文文档的纸张布局选项：文本宽度将设置为 曾卡库 宽度，文本高度为基线的整数倍。见 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' 只有DOCKET类）。

违约： '\\sphinxmaketitle'

在 1.8.3 版本发生变更: 原件 \maketitle FROM文档类不会被覆盖，因此可作为此键的某些自定义设置的一部分重新使用。

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

'releasename'

前缀值 'release' 标题页上的元素。至于 标题 和 作者 用于 latex_documents ，它作为 Latex 标记插入。

违约： 'Release'

'tableofcontents'

“目录”调用。违约 '\\sphinxtableofcontents' 是未经修改的 \tableofcontents ，它本身可能由用户加载的包自定义。如果要生成不同的目录或在标题页和目录之间放置内容，则重写。

违约： '\\sphinxtableofcontents'

在 1.5 版本发生变更: 以前的意义 \tableofcontents 它本身被Sphinx改造了。这就造成了与修改它的专用软件包（如“tocoloft”或“etoc”）的不兼容。

'transition'

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

违约： '\n\n\\bigskip\\hrule\\bigskip\n\n'

在 1.2 版本加入.

在 1.6 版本发生变更: 移除不需要的 {{}} 之后 \\hrule .

'makeindex'

"makeindex" call, the last thing before \begin{document}. With '\\usepackage[columns=1]{idxlayout}\\makeindex' the index will use only one column. You may have to install idxlayout LaTeX package.

默认： '\\makeindex'

'printindex'

"printindex" call, the last thing in the file. Override if you want to generate the index differently, append some content after the index, or change the font. As LaTeX uses two-column mode for the index it is often advisable to set this key to '\\footnotesize\\raggedright\\printindex'. Or, to obtain a one-column index, use '\\def\\twocolumn[#1]{#1}\\printindex' (this trick may fail if using a custom document class; then try the idxlayout approach described in the documentation of the 'makeindex' key).

违约： '\\printindex'

'fvset'

自定义 fancyvrb Latex 包装。

The default value is '\\fvset{fontsize=auto}' which means that the font size will adjust correctly if a code-block ends up in a footnote. You may need to modify this if you use custom fonts: '\\fvset{fontsize=\\small}' if the monospace font is Courier-like.

默认： '\\fvset{fontsize=auto}'

在 1.8 版本加入.

在 2.0 版本发生变更: For 'xelatex' and 'lualatex' defaults to '\\fvset{fontsize=\\small}' as this is adapted to the relative widths of the FreeFont family.

在 4.0.0 版本发生变更: Changed default for 'pdflatex'. Previously it was using '\\fvset{fontsize=\\small}'.

在 4.1.0 版本发生变更: Changed default for Chinese documents to '\\fvset{fontsize=\\small,formatcom=\\xeCJKVerbAddon}'

由其他选项设置的不应被重写的键是：

'docclass' 'classoptions' 'title' 'release' 'author'

这个 sphinxsetup 配置设置

在 1.5 版本加入.

这个 'sphinxsetup' 关键 latex_elements 提供 Latex 类型自定义接口：：

latex_elements = {
    'sphinxsetup': 'key1=value1, key2=value2, ...',
}

默认为空。如果非空，它将作为参数传递给 \sphinxsetup 文档序言中的宏，如下所示：

\usepackage{sphinx}
\sphinxsetup{key1=value1, key2=value2,...}

上面使用的颜色由 svgnames “xcolor”包的选项：

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

可以插入使用 \sphinxsetup 直接将LaTeX宏放入文档正文，通过 raw 指令。本章在PDF输出中的开头使用以下插入内容来设置样式。这使用稍后将在中介绍的密钥 其他类似于css的内容 'sphinxsetup' 钥匙 。

.. raw:: latex

   \begingroup
   \sphinxsetup{%
      TitleColor={named}{DarkGoldenrod},
      % pre_border-width is 5.1.0 alias for verbatimborder
      pre_border-width=2pt,
      pre_border-right-width=8pt,
      % pre_padding is a 5.1.0 alias for verbatimsep
      pre_padding=5pt,
      % Rounded boxes are new at 5.1.0
      pre_border-radius=5pt,
      % TeXcolor reminds that syntax must be as for LaTeX \definecolor
      pre_background-TeXcolor={named}{OldLace},
      % ... and since 5.3.0 also xcolor \colorlet syntax is accepted and we
      %     can thus drop the {named}{...} thing if xcolor is available!
      pre_border-TeXcolor=Gold,
      % ... and even take more advantage of xcolor syntax:
      pre_border-TeXcolor=Gold!90,
      % add a shadow to code-blocks
      pre_box-shadow=6pt 6pt,
      pre_box-shadow-TeXcolor=gray!20,
      %
      % This 5.1.0 CSS-named option is alias for warningborder
      div.warning_border-width=3pt,
      % Prior to 5.1.0, padding for admonitions was not customizable
      div.warning_padding=6pt,
      div.warning_padding-right=18pt,
      div.warning_padding-bottom=18pt,
      % Assume xcolor has been loaded with its svgnames option
      div.warning_border-TeXcolor=DarkCyan,
      div.warning_background-TeXcolor=LightCyan,
      % This one is the only option with space separated input:
      div.warning_box-shadow=-12pt -12pt inset,
      div.warning_box-shadow-TeXcolor=Cyan,
      %
      % The 5.1.0 new name would be div.attention_border-width
      attentionborder=3pt,
      % The 5.1.0 name here would be div.attention_border-TeXcolor
      attentionBorderColor=Crimson,
      % The 5.1.0 name would be div.attention_background-TeXcolor
      attentionBgColor=FloralWhite,
      %
      % For note/hint/important/tip, the CSS syntax was added at 6.2.0
      % Legacy syntax still works
      noteborder=1pt,
      noteBorderColor=Olive,
      % But setting a background color via the new noteBgColor means that
      % it will be rendered using the same interface as warning type
      noteBgColor=Olive!10,
      % We can customize separately the four border-widths, and mimic
      % the legacy "light" rendering, but now with a background color:
      % div.note_border-left-width=0pt,
      % div.note_border-right-width=0pt,
      % Let's rather for variety use lateral borders:
      div.note_border-top-width=0pt,
      div.note_border-bottom-width=0pt,
      %
      % As long as only border width and border color are set, *and* using
      % for this the old interface, the rendering will be the "light" one
      hintBorderColor=LightCoral,
      % but if we had used div.hint_border-TeXcolor or *any* CSS-named
      % option we would have triggered the more complex "heavybox" code.
   }

这放在章节源代码的末尾，以结束配置的范围：

.. raw:: latex

   \endgroup

Boolean键的LaTeX语法要求 lowercase true 或 false e.g 'sphinxsetup': "verbatimwrapslines=false" 。如果将布尔键设置为 true ， =true 是可选的。逗号和等号周围的空格被忽略，LaTeX宏内的空格可能很重要。请勿使用引号将数值引起来，无论数值还是字符串。

bookmarksdepth

控制PDF中可折叠书签面板的深度。可以是一个数字(例如 3 )或胶乳分段名称(例如 subsubsection 即不带反斜杠)。有关详细信息，请参阅 hyperref Latex 医生。

默认： 5

在 4.0.0 版本加入.

hmargin, vmargin

水平（分别为垂直）页边距，传递为 hmargin （RESP） vmargin 选项为 geometry 包裹。例子：：

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

日本文档目前只接受这些参数的一维格式。这个 geometry 然后传递合适的选项，使文本宽度设置为 曾卡库 宽度和文本高度设置为基线跳过的整数倍，与边距最接近。

违约： 1in （相当于 {{1in,1in}} ）

提示

日语 'manual' 点大小的DocClass 11pt 或 12pt 使用 nomag 附加文档类选项（参见 'extraclassoptions' 关键 latex_elements ）或所谓的tex“真”单位：

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

在 1.5.3 版本加入.

marginpar

这个 \marginparwidth Latex 尺寸。对于日语文档，该值被修改为 曾卡库 宽度。

违约： 0.5in

在 1.5.3 版本加入.

verbatimwithframe

布尔值，用于指定 code-block S和字面包含是框定的。将其设置为 false 不停用包“Framed”，因为它仍在用于可选的背景色。

违约： true .

verbatimwrapslines

布尔值指定是否在 code-block 的内容已包装。

如果 true ，换行符可能出现在空格(换行符之前的最后一个空格将使用特殊符号呈现)，以及ASCII标点符号字符(即不是字母或数字)。只要长字符串没有断点，它就会移到下一行。如果它的长度大于线条宽度，它将溢出。

违约： true

verbatimforcewraps

布尔值，用于指定在 code-block 应强制包装的内容，以免因长字符串而溢出。

备注

据推测， Pygments LaTeXForMatter尚未与其一起使用 texcomments 或允许附加(任意)胶乳加价的类似选项。

此外，在以下情况下 latex_engine 设置为 'pdflatex' ，只有Unicode代码点的默认LaTeX处理，即 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} 或(仅限套餐 xcolor ) {HTML}{808080} 或者..。

  • 或遵循 \colorlet 来自包的命令 xcolor (然后必须存在于LaTeX安装中)，例如 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 S。

默认： {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 指令，或者也可以从与 container class 并使用这样的 \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

周围边框的宽度 code-block S。另见 其他类似于css的内容 'sphinxsetup' 钥匙 为 pre_border-width 。

违约： \fboxrule

shadowsep

内容和框架之间的分离 contents 和 topic 盒子。

看见 其他类似于css的内容 'sphinxsetup' 钥匙 用于别名 div.topic_padding 。

违约： 5pt

shadowsize

右侧和底部的横向“阴影”的宽度。

看见 其他类似于css的内容 'sphinxsetup' 钥匙 为 div.topic_box-shadow 其允许分别配置垂直和水平阴影的宽度。

违约： 4pt

在 6.1.2 版本发生变更: 修复了在 5.1.0 它无意中修改了主题框的宽度，更糟糕的是，它利用了这个关键的突破PDF构建。

shadowrule

周围边框的宽度 topic 盒子。另请参阅 其他类似于css的内容 'sphinxsetup' 钥匙 为 div.topic_border-width 。

违约： \fboxrule

noteBorderColor, hintBorderColor, importantBorderColor, tipBorderColor

Sphinx在LaTeX中用于设置样式的两条水平线的颜色 note 键入警告。

违约： {{rgb}}{{0,0,0}} （黑色）

noteBgColor, hintBgColor, importantBgColor, tipBgColor

背景的可选颜色。它是先验设置为白色的，但不使用，除非已明确设置，这样做会触发Sphinx切换到更复杂的LaTeX代码，该代码也用于 warning 键入警告。然后还有其他选项，如中所述 其他类似于css的内容 'sphinxsetup' 钥匙 。

违约： {{rgb}}{{1,1,1}} （白色）

在 6.2.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' 钥匙 使用语法(例如 div.note_border-width=1pt 代替 noteborder=1pt )，或 any 选项使用类似于css的名称，则边框是一个完整的框架，并且此参数还设置其左侧和右侧的宽度。

违约： 0.5pt

warningBorderColor, cautionBorderColor, attentionBorderColor, dangerBorderColor, errorBorderColor

警告框的颜色。

违约： {{rgb}}{{0,0,0}} （黑色）

warningBgColor, cautionBgColor, attentionBgColor, dangerBgColor, errorBgColor

各个警告的背景颜色。

违约： {{rgb}}{{1,1,1}} （白色）

warningborder, cautionborder, attentionborder, dangerborder, errorborder

框架的宽度。看见 其他类似于css的内容 'sphinxsetup' 钥匙 用于允许单独配置每个边框宽度的按键。

违约： 1pt

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 告诫可以是这样的风格。为他们使用 any 将触发使用比默认情况下使用的更复杂的LaTeX代码 (sphinxheavybox VS sphinxlightbox )。设置新的 noteBgColor (或 hintBgColor ，...)还会触发使用 sphinxheavybox 为 note (或 hint 、...)。

也许在未来，这些5.1.0(和6.2.0)的新设置将有选择地从一些真正的CSS外部文件导入，但目前它们必须通过 'sphinxsetup' 接口(或 \sphinxsetup LaTeX命令通过 raw 指令)，并且只模仿了css语法。

重要

如果不遵守输入语法，则可能会发生导致构建失败的低级LaTeX错误。

  • 特别是，对于前面描述的其他颜色相关选项，必须输入颜色，即在 \definecolor 语法或，如果是包 xcolor 是可用的(然后自动使用)也是 \colorlet 语法：：

    ...<other options>
div.warning_border-TeXcolor={rgb}{1,0,0},% (always works)
div.error_background-TeXcolor=red!10,% (works only if xcolor is available)
...<other options>

  • 用冒号代替等号将打碎 Latex 。

  • ...border-width 或 ...padding 期望得到一个 single 尺寸：它们目前还不能与空格分隔的尺寸一起使用。

  • ...top-right-radius 等人的研究。值可以是单个或 two 空格分隔的维度。

  • 尺寸规格必须使用TeX单位，例如 pt 或 cm 或 in 。这个 px 单位被识别为 pdflatex 和 lualatex 但不是通过 xelatex 或 platex 。

  • 允许这样的规范是所谓的“维度表达式”，例如 \fboxsep+2pt 或 0.5\baselineskip 是有效的输入。只有在排版时才会计算表达式。但是，如果像在这些示例中一样使用Tex控制序列将反斜杠加倍，或者使用原始的Python字符串作为 'sphinxsetup' 钥匙。

  • As a rule, avoid inserting unneeded spaces in the key values: especially for the radii an input such 2 pt 3pt will break LaTeX. Beware also that \fboxsep \fboxsep will not be seen as space separated in LaTeX. You must use something such as {\fboxsep} \fboxsep. Or use directly 3pt 3pt which is a priori equivalent and simpler.

所有选项都以类似的模式命名，该模式取决于 prefix ，然后是下划线，然后是属性名称。

指令

选项前缀

Latex 环境

code-block

pre

sphinxVerbatim

topic

div.topic

sphinxShadowBox

contents

div.topic

sphinxShadowBox

note

div.note

sphinxnote using sphinxheavybox

warning

div.warning

sphinxwarning (使用 sphinxheavybox )

警告式

div.<type>

sphinx<type> (使用 sphinxheavybox )

下面是这些选项及其常见的默认设置。在下面替换 <prefix> 通过如上所述的实际前缀。不要忘记用下划线将前缀与属性名称隔开。

  • <prefix>_border-top-width ，
    <prefix>_border-right-width ，
    <prefix>_border-bottom-width ，
    <prefix>_border-left-width ，
    <prefix>_border-width 。后者可能(目前)只是一个 single 维度，然后设置所有其他四个维度。

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

    • \fboxrule (即先验 0.4pt )用于 code-block ，

    • \fboxrule 为 topic 或 contents 指令，

    • 1pt 为 warning 以及其他“强烈”的告诫，

    • 0.5pt 为 note 以及其他“轻描淡写”的警告。在没有使用css命名选项的情况下，为它们使用的“lightbox”的框架样式将由更丰富的“Heavybox”IF设置模仿 border-left-width 和 border-right-width 两者均为 0pt 。

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

  • <prefix>_padding-top ，
    <prefix>_padding-right ，
    <prefix>_padding-bottom ，
    <prefix>_padding-left ，
    <prefix>_padding 。后者可能(目前)只是一个 single 维度，然后设置所有其他四个维度。

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

    • \fboxsep (即先验 3pt )用于 code-block ，

    • 5pt 为 topic 或 contents 指令，

    • 的特殊值 warning 以及其他“强烈”的警告，这确保了向后兼容的行为。

      重要

      在5.1.0之前，不能通过LaTeX输出单独定制PDF中警告类型框的填充。填充和边框宽度之和(例如为 warning 通过 warningborder ，现在也命名为 div.warning_border-width )被保持在某个恒定值。这将边框宽度限制为较小的值，否则边框可能会与文本内容重叠。此行为保留为默认行为。

    • 默认情况下，遵循相同的填充行为 note 或使用时的其他“轻”警告 sphinxheavybox 。

  • <prefix>_border-top-left-radius ，
    <prefix>_border-top-right-radius ，
    <prefix>_border-bottom-right-radius ，
    <prefix>_border-bottom-left-radius ，
    <prefix>_border-radius 。最后一个关键点将前四个设置为其赋值。每个密钥值可以是单个或 two ，这些维度随后被空格分隔。

    默认情况下，所有四个角都是圆形或直角，半径相同：

    • \fboxsep (即先验 3pt )用于 code-block (自6.0.0起)。

    • 0pt 对于所有其他指令，这意味着使用直角。

    参见上面关于LaTeX中带有空格的陷阱的备注。

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

    • 这个 none 关键字，

    • 或单一维度(给出x偏移和y偏移两者)，

    • 或二维(由空格隔开)，

    • 或后跟关键字的两个维度 inset 。

    X偏移量和y偏移量可以是负数。缺省值为 none ， except 对于 topic 或 contents 指令，它所针对的 4pt 4pt ，即阴影的宽度为 4pt 并延伸到框架的右侧和下方。横向阴影随后延伸到页面右边距。

  • <prefix>_border-TeXcolor ，
    <prefix>_background-TeXcolor ，
    <prefix>_box-shadow-TeXcolor ，
    <prefix>_TeXcolor 。这些是颜色。

    阴影颜色在所有情况下都默认为 {rgb}{0,0,0} 也就是说，转到黑色。

    从6.0.0开始，边框颜色和背景颜色 code-block ，即 pre 前缀，分别默认为 {RGB}{32,32,32} 和 {gray}{0.95} 。它们之前默认为黑色，分别为白色。

    对于所有其他类型，边框颜色默认为黑色，背景颜色默认为白色。

    这个 <prefix>_TeXcolor 表示css属性“COLOR”，即它影响内容的文本颜色。至于其他三个选项，命名 TeXcolor 要强调的是，输入语法是用于颜色的Tex语法，而不是HTML/CSS语法。IF包 xcolor 在LaTeX安装中可用，您可以使用直接命名的颜色作为键值。考虑传递选项，例如 dvipsnames ， svgnames 或 x11names 至 xcolor 通过 'passoptionstopackages' 的关键字 latex_elements 。

    如果 <prefix>_TeXcolor 已设置，则一个 \color 命令被插入在指令内容的开始处；对于警告，该命令发生在再现警告类型的标题之后。

  • <prefix>_TeXextras ：如果设置，则其值必须是某个LaTeX命令或一些命令，例如 \itshape 。这些命令将被插入到内容的开头；对于警告，这将发生在复制警告类型的标题之后。

备注

  • 所有指令都支持 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标记；它确实会给行号上色，但如果要上色 only 他们必须要通过 fancyvrb 界面。

    • pre_TeXextras=\footnotesize for example may be replaced by usage of the latex_elements key 'fvset'. For 'lualatex' or 'xelatex' Sphinx includes in the preamble already \fvset{fontsize=\small} and this induces fancyvrb into overriding a \footnotesize coming from pre_TeXextras. One has to use pre_TeXextras=\fvset{fontsize=\footnotesize} syntax. Simpler to set directly the latex_elements key 'fvset'...

    将这些选项视为试验性选项，某些实现细节可能会更改。例如，如果 pre_TeXextras LaTeX命令由Sphinx放在它可以覆盖的另一个位置 'fvset' 效果，也许这就是将来版本中要做的事情。

  • 圆角框是使用 pict2e 接口到一些基本的PDF图形操作。如果找不到这个 Latex 包，构建将继续并渲染所有直角的长方体。

  • 椭圆角使用 ellipse 延伸的 Latex 包装 pict2e. 如果找不到这种 Latex 包装，圆角将是圆弧(如果是直角 pict2e 不可用)。

以下旧版行为当前不可自定义：

  • 为 code-block 、填充、边框宽度和阴影(如果加1)将进入页边距；代码行保持在同一位置，而与填充和边框宽度的值无关，当然，除了垂直移动以不因边框或外部阴影的宽度而覆盖其他文本之外。

  • 为 topic (及 contents) 阴影(如果在右侧)进入页边距，但边框和额外填充保留在文本区域内。告诫也是如此。

  • 这个 contents 和 topic 指令由具有相同选项的 div.topic 前缀：Sphinx LaTeX标记对这两个指令的使用相同 sphinxShadowBox 环境，该环境当前没有额外的分支，相反， sphinxadmonition 根据警告指令名称分支的环境，例如 sphinxnote 或 sphinxwarning 等等.。

Latex 宏和环境

“LaTeX Package”文件 sphinx.sty 加载提供支持宏(也称为命令)和环境的各种组件，这些组件用于从 latex 生成器，在转换为 pdf 通过LaTeX工具链。还有“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 ( this one has no argument )

    \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

    \sphinxstrong{#1}<space>

    \sphinxstylehinttitle

    idem

    \sphinxstyleimportanttitle

    idem

    \sphinxstyletiptitle

    idem

    \sphinxstylewarningtitle

    idem

    \sphinxstylecautiontitle

    idem

    \sphinxstyleattentiontitle

    idem

    \sphinxstyledangertitle

    idem

    \sphinxstyleerrortitle

    idem

    \sphinxstyleseealsotitle

    \sphinxstrong{#1}\par\nopagebreak

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

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

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

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

    在 6.2.0 版本加入: \sphinxstylenotetitle 等人的研究。这个 #1 指令的本地化名称，最后一个冒号。将其包装为 \sphinxremovefinalcolon{#1} 如果要移除最后一个冒号。例如：

    \renewcommand\sphinxstylewarningtitle[1]{%
  \underline{\textbf{\sphinxremovefinalcolon{#1}}}\par
}
\renewcommand{\sphinxstylenotetitle}[1]{%
  \textit{\textbf{\sphinxremovefinalcolon{#1}}}\par\nobreak
  % LaTeX syntax is complex and we would be better off using \hrule.
  {\parskip0pt\noindent}%
  \raisebox{1ex}%
   {\makebox[\linewidth]{\textcolor{sphinxnoteBorderColor}{\dotfill}}}
  % It is complex to obtain nice vertical spacing for both a paragraph
  % or a list following up; this set-up is better for a paragraph next.
  \par\vskip-\parskip
}

  • \sphinxtableofcontents ：包装器（在 sphinxhowto.cls 而在 sphinxmanual.cls 标准的 \tableofcontents . 宏 \sphinxtableofcontentshook 在其扩展过程中执行 \tableofcontents 本身。

    在 1.5 版本发生变更: 以前，意思是 \tableofcontents 被Sphinx修改。

    在 2.0 版本发生变更: 硬编码的重新定义 \l@section 和 \l@subsection 以前在加载期间完成 'manual' docclass现在稍后通过执行 \sphinxtableofcontentshook . 此宏也由 'howto' DocClass，但默认为空。

    提示

    If adding to preamble the loading of tocloft package, also add to preamble \renewcommand\sphinxtableofcontentshook{} else it will reset \l@section and \l@subsection cancelling tocloft customization.

  • \sphinxmaketitle ：用作 'maketitle' latex_elements 钥匙。在类文件中定义 sphinxmanual.cls 和 sphinxhowto.cls .

    在 1.8.3 版本发生变更: 从前， \maketitle 从 Latex 文档类修改了Sphinx。

  • \sphinxbackoftitlepage 为了 'manual' docclass，如果定义了它，它将在 \sphinxmaketitle ，决赛前 \clearpage . 要么使用 'maketitle' 密钥或 'preamble' 关键 latex_elements 添加自定义定义的步骤 \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=true 在7.0.0，这取决于在此之前的反馈。

组合在一起 addstrut, padding-bottom=0pt, padding-top=1pt 往往令人满意。

参考 其他类似于css的内容 'sphinxsetup' 钥匙 获取有关其他键的重要语法信息。默认配置不使用阴影，边框宽度为 \fboxrule ，一个填充物 \fboxsep ，带半径的圆角 \fboxsep 以及与代码块的默认呈现一样的背景和边框颜色。

当一个 \sphinxbox Usage嵌套在另一个选项中，它将忽略外部选项的选项：它首先将所有选项重置为它们在应用外部框选项之前的默认状态，然后应用它自己的特定选项。

用户可以通过以下命令修改这些缺省值 \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 Laex标记)，唯一的区别是它们最初有一组额外的默认附加组件。

在上面的示例中，您可能可以使用 \renewcommand 语法，如果您喜欢它的话 \protected\def (带 [1] 代替 #1 然后)。

环境

  • A figure 可能具有带有任意主体元素的可选图例：它们在 sphinxlegend 环境。默认定义问题 \small 结束 \par .

    在 1.5.6 版本加入: 以前 \small 是用 Latex 笔和结尾硬编码的 \par 缺乏。

  • 与警告相关的环境：

    • sphinxnote ，

    • sphinxhint ，

    • sphinximportant ，

    • sphinxtip ，

    • sphinxwarning ，

    • sphinxcaution ，

    • sphinxattention ，

    • sphinxdanger ，

    • sphinxerror .

    他们可能是 \renewenvironment D，然后必须用一个参数定义(例如，它是通知的标题 Warning: 为 warning 指令，如果英语是文档语言)。它们的默认定义使用 sphinxheavybox (最后5个)或 sphinxlightbox 环境，配置为使用特定于每种类型的参数(颜色、边框厚度)，可以通过 'sphinxsetup' 弦乐。

    在 1.5 版本发生变更: 使用公共环境名称，单独自定义参数，如 noteBorderColor ， noteborder ， warningBgColor ， warningBorderColor ， warningborder ，…

  • 的环境。 seealso 指令： sphinxseealso 。它接受一个参数，该参数将是本地化字符串 See also 后面跟一个冒号。

    在 6.1.0 版本加入.

    在 6.2.0 版本发生变更: 冒号是标记的一部分，而不是由环境插入，以与警告的一般处理方式保持一致。

  • 这个 contents 指令(带有 :local: 选项)和 topic 指令由环境执行 sphinxShadowBox 。

    在 1.4.2 版本加入: 以前的代码被重构成允许分页符的环境。

    在 1.5 版本发生变更: 选项 shadowsep ， shadowsize ， shadowrule .

  • 文字块(通过 :: 或 code-block )，使用以下方式实现 sphinxVerbatim 环境，它是对 Verbatim 来自包的环境 fancyvrb.sty 。它添加了对顶端标题和长行换行的处理，以及允许分页符的框架。在表中，使用的环境是 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 版本加入.

  • 章节，小节。。。标题是用 蒂莱塞克 的 \titleformat 命令。

  • 对于 'manual' docclass，可以使用自定义章节标题 头孢菌素 的命令 \ChNameVar ， \ChNumVar ， \ChTitleVar . 文件 sphinx.sty 在以下情况下具有自定义重新定义 头孢菌素 选项 Bjarne .

    在 1.5 版本发生变更: 以前，使用 头孢菌素 与其他样式不同 Bjarne 功能失调。

  • 文献片 container 指令在LaTeX输出中受支持：让具有名称的容器类 foo 通过LaTeX影响最终的PDF，只需要在前言中定义一个环境 sphinxclassfoo 。一个简单的例子是：

    \newenvironment{sphinxclassred}{\color{red}}{}

    目前，类名称必须仅包含ascii字符，并避免使用LaTeX特有的字符，如 \ 。

    在 4.1.0 版本加入.

提示

作为一个实验特性，如果您有一个名为 _templates/latex.tex_t 在你的项目中。

其他文件 longtable.tex_t ， tabulary.tex_t 和 tabular.tex_t 可以添加到 _templates/ 配置表呈现的某些方面（如标题位置）。

在 1.6 版本加入: 目前，所有模板变量都不稳定且未记录。