Latex 定制

不像 the HTML builders , the 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' 描述了关键字 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'

Added in version 1.5.

'passoptionstopackages'

一根将位于序言早期的字符串，旨在包含 \PassOptionsToPackage{options}{foo} 命令.

提示

它也可以在前言中非常早的时候用来加载 Latex 包。例如包 fancybox 与通过 'preamble' 密钥，它必须早点加载。

违约： ''

Added in version 1.4.

'babel'

“babel”包包含，默认 r'\usepackage{babel}' (the合适的文档语言字符串作为类选项传递，并且 english 如果没有语言则使用。）对于日语文档，默认为空字符串。

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

提示

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

默认： r'\usepackage{babel}' (for日本文件）

在 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 .

在 7.4.0 版本发生变更: 对于法国人来说， 'lualatex' 默认为使用 babel .

'fontpkg'

字体包包含。默认为 'pdflatex' 是：：

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

For 'xelatex' and 'lualatex' on the other hand the \setmainfont, \setsansfont and \setmonofont commands of LaTeX package fontspec (included via 'fontenc') are used to set up the OpenType fonts GNU FreeSerif, FreeSans, and FreeMono (scaled with ratio 0.9) as document fonts.

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

在 2.0 版本发生变更: 将一些字体替换命令转换为帮助支持文档中偶尔出现的希腊文或西里尔文， 'pdflatex' 发动机在4.0.0，这些命令被移至 'fontsubstitution' 钥匙

在 4.0.0 版本发生变更: 默认字体设置已更改。 如上所示，它仍然使用Times和Helvetica克隆来进行衬线和无衬线，但通过更好、更完整的TeX字体和相关的LaTeX包。 单层字体已更改，以更好地匹配《泰晤士报》克隆版。

在 8.1.0 版本发生变更: 与Unicode引擎一起使用的单空间字体FreeMono是大规模加载的 0.9 . 这取代了以前的机制， 'fvset' 哪些配置了要使用的代码块 \small . 内联文字现在更适合其周围的文本，并且更容易设置自定义字体，因为 'fvset' 默认情况下不再干预。

'fncychap'

Inclusion of the "fncychap" package (which makes fancy chapter titles), default r'\usepackage[Bjarne]{fncychap}' for English documentation (this option is slightly customized by Sphinx), r'\usepackage[Sonny]{fncychap}' for internationalized docs (because the "Bjarne" style uses numbers spelled out in English). Other "fncychap" styles you can try are "Lenny", "Glenn", "Conny", "Rejne" and "Bjornstrup". You can also set this to '' to disable fncychap.

Default: r'\usepackage[Bjarne]{fncychap}' for English documents, r'\usepackage[Sonny]{fncychap}' for internationalized documents, and '' for Japanese documents.

'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' （这里，上，下，第页）

Added in version 1.3.

'atendofbody'

附加文档内容（在索引之前）。

违约： ''

Added in version 1.5.

'extrapackages'

附加 Latex 包装。例如：

latex_elements = {
    'extrapackages': r'\usepackage{isodate}'
}

指定的 Latex 包将在hyperref包和Sphinx扩展包加载之前加载。

提示

如果要在hyperref之后加载其他 Latex 包，请使用 'preamble' 而不是钥匙。

违约： ''

Added in version 2.3.

'footer'

其他页脚内容（在索引之前）。

违约： ''

自 1.5 版本弃用: 使用 'atendofbody' 而不是钥匙。

除非在特殊情况下，否则不需要重写的键是：

'extraclassoptions'

默认值为空字符串。例子： 'extraclassoptions': 'openany' 允许章节（用于 'manual' 键入）从任何页面开始。

违约： ''

Added in version 1.2.

在 1.6 版本发生变更: 添加了此文档。

'maxlistdepth'

默认情况下，对于嵌套列表和类似引号的环境，LaTex最多允许6个级别，最多允许4个枚举列表和4个项目符号列表。例如，将此键设置为 '10' （作为字符串）将允许最多10个嵌套级别（各种类型）。将其保留为空字符串意味着遵守 Latex 默认值。

警告

  • 使用此密钥可能会证明与执行自己列表自定义的某些 Latex 包或特殊文档类不兼容。

  • 按键设置为静默 忽略 如果 \usepackage{{enumitem}} 在文档序言中执行。然后使用这个 Latex 包的专用命令。

违约： 6

Added in version 1.5.

'inputenc'

“inputenc”包包含。

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

备注

如果使用 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 版本发生变更: 先前 r'\usepackage[utf8]{inputenc}' 用于所有编译器。

'cmappkg'

“cmap”包裹。

默认： r'\usepackage{cmap}'

Added in version 1.2.

'fontenc'

其默认情况是， 'pdflatex' 作为 latex_engine ，是 r'\usepackage[T1]{fontenc}' . 更换（如果使用 'pdflatex' ）与：

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

  • r'\usepackage[LGR,T1]{fontenc}' 如果您偶尔需要希腊字母（Ÿ ω ωμ a Sigma），

  • 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 (with下面描述的一些附加内容）并选择NU FreeSerif字体作为正文字体。 看到 'fontpkg' .

在 1.5 版本发生变更: 默认为 r'\usepackage{fontspec}' 如果 latex_engine 设置为 'xelatex' .

在 1.6 版本发生变更: 默认为 r'\usepackage{fontspec}' 如果 latex_engine 设置为 'lualatex' .

在 2.0 版本发生变更: 'lualatex' executes additionally \defaultfontfeatures[\rmfamily,\sffamily]{} to disable TeX ligatures for << and >>.

在 2.0 版本发生变更: 如果出现以下情况，额外的LaTeX配置将自动执行 LGR , T2A ，或者 X2 在此键中检测到，以便偶尔支持希腊语或西里尔语 'pdflatex' .

在 2.2.1 版本发生变更: 以希腊语为主要语言的文档默认为 'xelatex' 并且不应该设置 'fontenc' 键，将加载 fontspec .

在 2.3.0 版本发生变更: 'xelatex' executes \defaultfontfeatures[\rmfamily,\sffamily]{} in order to avoid contractions of -- into en-dash and also transforms of straight quotes into curly quotes (which otherwise would happen even with smartquotes set to False).

'fontsubstitution'

如果被忽视 'fontenc' 未配置为使用 LGR 或 X2 （或 T2A ). 如果 'fontpkg' 该键被配置为与已知的某些TeX字体一起使用 LGR 或 X2 编码，将此设置为空字符串。 否则就会默认。

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

Added in version 4.0.0.

'textgreek'

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

它被忽视了 'platex' , 'xelatex' 或 'lualatex' 作为 latex_engine 并且默认为空字符串或 r'\usepackage{textalpha}' 为 'pdflatex' 取决于 'fontenc' 钥匙与 LGR 或不. 只有LaTeX专家用户可能想要自定义此密钥。

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

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

Added in version 2.0.

'geometry'

"geometry" package inclusion, defaults to r'\usepackage{geometry}' or r'\usepackage[dvipdfm]{geometry}' for Japanese documents. The Sphinx LaTeX style file executes additionally:

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

可通过相应的 'sphinxsetup' options .

Added in version 1.5.

在 1.5.2 版本发生变更: dvipdfm 选项如果 latex_engine 是 'platex' .

Added in version 1.5.3: 这个 'sphinxsetup' keys for the margins .

在 1.5.3 版本发生变更: The location in the LaTeX file has been moved to after \usepackage{sphinx} and \sphinxsetup{..}, hence also after insertion of 'fontpkg' key. This is in order to handle the paper layout options in a special way for Japanese documents: the text width will be set to an integer multiple of the zenkaku width, and the text height to an integer multiple of the baseline. See the hmargin documentation for more.

'hyperref'

包含“Hyperref”包;还加载包“Hypcap”和问题 \urlstyle{same} .这是在之后进行的 sphinx.sty 加载文件并在执行的内容之前 'preamble' 钥匙

注意

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

Added in version 1.5: 以前这是从内部完成的 sphinx.sty .

'maketitle'

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

提示

If the key value is set to r'\newcommand\sphinxbackoftitlepage{<Extra material>}\sphinxmaketitle', then <Extra material> will be typeset on back of title page ('manual' docclass only).

默认： r'\sphinxmaketitle'

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

Added in version 1.8.3: \sphinxbackoftitlepage 可选宏。 也可以在里面定义 'preamble' 而不是这把钥匙。

'releasename'

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

违约： 'Release'

'tableofcontents'

"tableofcontents" call. The default of r'\sphinxtableofcontents' is a wrapper of unmodified \tableofcontents, which may itself be customized by user loaded packages. Override if you want to generate a different table of contents or put content between the title page and the TOC.

默认： r'\sphinxtableofcontents'

在 1.5 版本发生变更: 以前的含义 \tableofcontents 它本身被狮身X修改过。这与修改它的专用包（例如“tocloft”或“etoc”）不兼容。

'transition'

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

Default: '\n\n\\bigskip\\hrule\\bigskip\n\n'

Added in version 1.2.

在 1.6 版本发生变更: 删除不需要 {} 以前位于 \hrule .

'makeindex'

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

默认： r'\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 r'\footnotesize\raggedright\printindex'. Or, to obtain a one-column index, use r'\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).

默认： r'\printindex'

'fvset'

自定义 fancyvrb Latex 包装。

The default value is r'\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 when using a custom monospace font, for example set it to r'\fvset{fontsize=\small}' if it is Courier-like (for Unicode engines, it is recommended to use rather the Scale interface of \setmonofont LaTeX command from fontspec).

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

Added in version 1.8.

在 2.0 版本发生变更: For 'xelatex' and 'lualatex' defaults to r'\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 r'\fvset{fontsize=\small}'.

在 4.1.0 版本发生变更: Changed default for Chinese documents to 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 配置设置

Added in version 1.5.

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

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

布尔键的LaTeX语法需要 lowercase true 或 false e.g 'sphinxsetup': "verbatimwrapslines=false" . 如果将布尔键设置为 true , =true is optional.逗号和等式周围的空白被忽略，LaTeX宏内部的空白可能很重要。不要使用记号/引号来括起字符串或数字值。

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

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

可以插入 \sphinxsetup LaTeX宏通过 raw 指令：

.. 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 在 development repository .

上例中使用的颜色可以通过传递 svgnames “xColor”包的选项：：

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

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

默认： 5

Added in version 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',

Added in version 1.5.3.

marginpar

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

违约： 0.5in

Added in version 1.5.3.

mathnumsep

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

Added in version 8.1.0.

verbatimwithframe

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

违约： true .

verbatimwrapslines

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

如果 true ，断点可能会发生在空白处（将使用特殊符号呈现分隔符之前的最后一个空白），也可能发生在ASCI标点符号处（即不是字母或数字处）。每当长字符串没有断点时，它就会移动到下一行。如果它的长度比行宽长，它就会溢出。

违约： true

verbatimforcewraps

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

备注

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

此外，在以下情况下 latex_engine 设置为 'pdflatex' ，只有Unicode代码点的默认LaTeX处理，即 utf8 不 utf8x 是被允许的。

默认： false

Added in version 3.5.0.

verbatimmaxoverfull

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

默认： 3

Added in version 3.5.0.

verbatimmaxunderfull

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

由于缺省值被设置为较高的值，因此只有在超满的情况下才会触发强制算法，即，在存在长于全线宽的字符串的情况下。将此选项设置为 0 要强制所有输入行在当前可用行宽处硬换行：：

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

对于给定的代码块，这可以通过使用原始LaTeX指令在本地插入合适的 \sphinxsetup (之前和之后)到LaTeX文件。

默认： 100

Added in version 3.5.0.

verbatimhintsturnover

用于指定代码块在分页符的情况下是否显示“下一页继续”和“从上一页继续”提示的布尔值。

违约： true

Added in version 1.6.3.

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

verbatimcontinuedalign, verbatimcontinuesalign

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

违约： r

Added in version 1.7.

parsedliteralwraps

布尔值指定是否在 parsed-literal 的内容应换行。

违约： true

Added in version 1.5.2: 将此选项值设置为 false 来恢复以前的行为。

inlineliteralwraps

用于指定内联文本中是否允许换行的布尔值：但当前仅在字符之后插入额外的潜在断点（除了空格处的 Latex 或连字符所允许的断点之外） . , ; ? ! / 和 \ . 由于TeX内部结构，线路中的空白区域将被拉伸（或缩小）以适应断线。

违约： true

Added in version 1.5: 将此选项值设置为 false 来恢复以前的行为。

在 2.3.0 版本发生变更: 在处添加了潜在断点 \ 字符。

verbatimvisiblespace

当长代码行被拆分时，源代码行行距换行位置正前方的最后一个空格字符将使用此选项进行排版。

违约： \textcolor{{red}}{{\textvisiblespace}}

verbatimcontinued

在延续代码行的开头插入LaTeX宏。它的（复杂的.）默认字体设置一个指向右侧的红色小钩：

\makebox[2\fontcharwd\font`\x][r]{\textcolor{red}{\tiny$\hookrightarrow$}}

在 1.5 版本发生变更: 在1.4.2中增加了长代码行的换行。延续符号的默认定义更改为1.5，以适应各种字体大小(例如，代码块可以在脚注中)。

备注

颜色键值必须为：

  • 遵守的语法 \definecolor LaTeX命令，例如 VerbatimColor={rgb}{0.2,0.3,0.5} 或 {RGB}{37,23,255} 或 {gray}{0.75} 或 {HTML}{808080} 或者...

  • 或遵守的语法 \colorlet 来自包的命令 xcolor 例如 VerbatimColor=red!10 或 red!50!green 或 -red!75 或 MyPreviouslyDefinedColor 或者...参阅 xcolor 此语法的文档。

在 5.3.0 版本发生变更: 以前只有 \definecolor 语法被接受。

TitleColor

标题的颜色(通过使用包“titlesec”进行配置)。

违约： {{rgb}}{{0.126,0.263,0.361}}

InnerLinkColor

传递给 hyperref 作为的价值 linkcolor 和 citecolor 。

违约： {{rgb}}{{0.208,0.374,0.486}} .

OuterLinkColor

传递给 hyperref 作为的价值 filecolor ， menucolor ，以及 urlcolor 。

违约： {{rgb}}{{0.216,0.439,0.388}}

VerbatimColor

的背景色 code-block S。

默认： {RGB}{242,242,242} (same作为 {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}}

Added in version 1.6.6.

TableRowColorHeader

设置表格标题行(全部)的背景颜色。

它只有在以下情况下才会产生效果 latex_table_style 含 'colorrows' 或者如果为该表分配了 colorrows 班级。对于具有以下参数的表，它将被忽略 nocolorrows 班级。

As for the other 'sphinxsetup' keys, it can also be set or modified from a \sphinxsetup{...} LaTeX command inserted via the raw directive, or also from a LaTeX environment associated to a container class and using such \sphinxsetup{...}.

默认： {gray}{0.86}

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

Added in version 5.3.0.

TableRowColorOdd

设置表格中奇数行的背景颜色(行计数开始于 1 在第一个非标题行)。只有在以下情况下才有效 latex_table_style 含 'colorrows' 或对于分配给 colorrows 班级。

默认： {gray}{0.92}

还有就是 TableMergeColorOdd 。

Added in version 5.3.0.

TableRowColorEven

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

默认 {gray}{0.98}

还有就是 TableMergeColorEven 。

Added in version 5.3.0.

verbatimsep

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

看见 其他类似于css的内容 'sphinxsetup' 钥匙 因为它的别名 pre_padding 和额外的钥匙。

默认： \fboxsep

verbatimborder

周围边框的宽度 code-block S。另见 其他类似于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包的名称。 其默认值动态设置为 fontawesome6 , fontawesome5 ，或者 fontawesome ，或者 none ，具体取决于使用的LaTeX安装中是否存在具有这些名称的包。 LaTeX代码将使用 \faIcon 命令if with fontawesome6/fontawesome5 ，而且 \faicon 如果用 fontawesome . 在后一种情况下，图标两者都用于 caution 和 danger 将默认为“螺栓”而不是“辐射”，这只在 fontawesome6 和 fontawesome5 .如果没有找到“Font Awesome”相关包（或者如果该选项被强制设置为 none ）图标会悄然掉落。 用户可以将此选项设置为某些特定的包，并且必须配置 div.note_title-icon 以及LaTeX包接口使用的类似密钥（请参阅 其他类似于css的内容 'sphinxsetup' 钥匙 这些额外的部分 'sphinxsetup' 钥匙）。

Added in version 7.4.0.

noteBorderColor, hintBorderColor, importantBorderColor, tipBorderColor

警告边界的颜色。

默认： {RGB}{134,152,155} .

在 7.4.0 版本发生变更.

noteBgColor, hintBgColor, importantBgColor, tipBgColor

警告背景的颜色。

默认： {RGB}{247,247,247} .

Added in version 6.2.0.

在 7.4.0 版本发生变更.

noteTextColor, hintTextColor, importantTextColor, tipTextColor

告诫内容的颜色。

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

Added in version 6.2.0: 在7.0.0之前将被视为试验性的。这些选项具有别名 div.note_TeXcolor (等)中描述的 其他类似于css的内容 'sphinxsetup' 钥匙 。使用后者将使Sphinx切换到更复杂的LaTeX代码，该代码支持中描述的可定制性 其他类似于css的内容 'sphinxsetup' 钥匙 。

noteTeXextras, hintTeXextras, importantTeXextras, tipTeXextras

Some extra LaTeX code (such as \bfseries or \footnotesize) to be executed at start of the contents.

默认：为空

Added in version 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可以在那里插入换行符）。

Default: \leavevmode\unskip

Added in version 1.5.

HeaderFamily

default \sffamily\bfseries. Sets the font used by headings.

其他类似于css的内容 'sphinxsetup' 钥匙

Added in version 5.1.0: 为 code-block ， topic 和 contents 指令性和强式警告 (warning ， error 、...)。

Added in version 6.2.0: 也就是 note ， hint ， important 和 tip 告诫可以是这样的风格。为他们使用 any 将触发使用比默认情况下使用的更复杂的LaTeX代码 (sphinxheavybox VS sphinxlightbox )。设置新的 noteBgColor (或 hintBgColor ，...)还会触发使用 sphinxheavybox 为 note (或 hint 、...)。

Added in version 7.4.0: 为 all 警告类型，默认配置确实设置了背景色（因此越丰富 sphinxheavybox 总是使用）。

重要

此外，默认情况下，所有警告标题都使用彩色行和图标进行样式化，这些行和图标是根据https://www.sphinx-doc.org上的Sphinx自己文档的当前渲染建模的。添加了类似CSS命名的键来设置标题的前景和背景颜色以及图标的LaTeX代码。

Added in version 7.4.0: 的可定制性 seealso 和 todo 指令。

Added in version 8.1.0: 单独的可定制性和新默认值 topic , contents, 和 sidebar 指令。

也许将来这些5.1.0（和6.2.0）新颖的设置将有选择地从一些真正的CSS外部文件导入，但目前它们必须通过 'sphinxsetup' 界面（或 \sphinxsetup 通过插入LaTeX命令 raw 指令）并且CSS语法仅被模仿。

重要

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

  • In particular colors must be input as for the other color related options previously described, i.e. either in the \definecolor syntax or via the \colorlet syntax:

    ...<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 期望得到一个 single 尺寸：它们目前还不能与空格分隔的尺寸一起使用。

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

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

  • It is allowed for such specifications to be so-called "dimensional expressions", e.g. \fboxsep+2pt or 0.5\baselineskip are valid inputs. The expressions will be evaluated only at the typesetting time. Be careful though if using as in these examples TeX control sequences to double the backslash or to employ a raw Python string for the value of the 'sphinxsetup' key.

  • 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

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 。后者可能(目前)只是一个 single 维度，然后设置所有其他四个维度。

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

    在 7.4.0 版本发生变更: 更改默认值 topic 和 error .

    在 8.1.0 版本发生变更: 不同于 topic 的默认值 sidebar .

  • <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 维度，然后设置所有其他四个维度。

    默认值：

    • 所有四 3pt 为 code-block ,

    • 6pt , 7pt , 6pt , 7pt 为 topic ,

    • 10pt , 7pt , 12pt , 7pt 为 contents,

    • 6pt , 5.5pt , 6pt , 5.5pt 为 sidebar ,

    • 6pt , 7pt , 6pt , 7pt 对于所有“轻”警告以及 seealso 和 todo 指令。

    • 6pt , 6.5pt , 6pt , 6.5pt 对于强烈的告诫类型，除了 error 它使用水平填充 6.25pt .

    在 7.4.0 版本发生变更: 所有默认设置均已更改，但 code-block . 警告的设置是为了使左（或右）填充加上左（或右）边框宽度相加始终为 7.5pt ，因此PDF中同一页面上的警告类型的内容垂直对齐。 这只是默认值的属性，而不是对用户可能选择的约束。

    在 8.1.0 版本发生变更: 单独的默认值 topic , contents, 和 sidebar .

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

    默认值：

    • 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偏置意味着阴影在左侧。 无论抵消是正还是负，阴影都会延伸到页面页边。

    The default is none except for the contents directive which uses 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语法。IF包 xcolor 在LaTeX安装中可用，您可以使用直接命名的颜色作为键值。考虑传递选项，例如 dvipsnames ， svgnames 或 x11names 至 xcolor 通过 'passoptionstopackages' 的关键字 latex_elements 。

    如果 <prefix>_TeXcolor 已设置，a \color 命令插入在指令内容的开头;对于警告，这发生在再现警告类型的标题之后。

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

下一个按键，用于警告， topic , contents, 和 sidebar ，所有三个都添加到7.4.0（后三个添加到8.1.0）。

  • div.<type>_title-background-TeXcolor ：标题的背景色。

    重要

    The colored title-row is produced as a result of the Sphinx default definitions for the various \sphinxstyle<type>title commands, which employ the \sphinxdotitlerow LaTeX command. See 宏指令.

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

  • div.<type>_title-icon: the LaTeX code responsible for producing the icon. If you want to modify the icons used by Sphinx, employ in these keys the \faIcon LaTeX command (assuming either fontawesome6 or fontawesome5 LaTeX package is available on your system). For example the default for note is div.note_title-icon=\faIcon{info-circle} with fontawesome5 and div.note_title-icon=\faIcon{circle-info} with fontawesome6 (which is used automatically if available). If your system only provides the fontawesome package (automatically detected) use its command \faicon rather in order to modify the choice of icons. The iconpackage key can be used to use some other package providing icons, use then the commands suitable to that package as values of the div.<type>_title-icon keys.

备注

  • 所有指令都支持 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 (as an example) is equivalent to setting 'fvset' key value to r'\fvset{fontsize=\footnotesize}'.

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

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

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

以下遗留行为适用：

  • 为 code-block 或 literalinclude 、填充、边框宽度和阴影（如果有的话）将进入页边距;代码行保持在同一位置，独立于填充和边框宽度的值，当然除了垂直移动之外，以免由于边框或外部阴影的宽度而覆盖其他文本。

  • 对于其他指令，阴影水平延伸到页面页边，但边框和额外的填充保留在文本区域内。

  • code-block 和 literalinclude 使用相同的LaTeX环境和命令，不能单独定制。

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] 有更大的括号，请参阅来源

    Added in version 1.4.5: 使用 \sphinx 带前缀的宏名，以限制与 Latex 包冲突的可能性。

    Added in version 1.8: \sphinxguilabel

    Added in version 3.0: \sphinxkeyboard

    Added in version 6.2.0: \sphinxparam, \sphinxsamedocref

    Added in version 7.1.0: \sphinxparamcomma which defaults to a comma followed by a space and \sphinxparamcommaoneperline. It is sed for one-parameter-per-line signatures (see maximum_signature_line_length) and defaults to \texttt{,}.

    Signatures of Python functions are rendered as name<space>(parameters) or name<space>[type parameters]<space>(parameters) (see PEP 695) where the length of <space> is set to 0pt by default. This can be changed via \setlength{\sphinxsignaturelistskip}{1ex} for instance.

  • 更多文本样式：

    姓名， 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

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

    Added in version 1.5: These macros were formerly hard-coded as non customizable \texttt, \emph, etc...

    Added in version 1.6: \sphinxstyletheadfamily which defaults to \sffamily and allows multiple paragraphs in header cells of tables.

    Added in version 1.6.3: \sphinxstylecodecontinued and \sphinxstylecodecontinues.

    Added in version 1.8: \sphinxstyleindexlettergroup, \sphinxstyleindexlettergroupDefault.

    Added in version 6.2.0: \sphinxstylenotetitle et al. The #1 is the localized name of the directive, with a final colon. Wrap it as \sphinxremovefinalcolon{#1} if this final colon is to be removed.

    Added in version 7.4.0: 添加了 \sphinxdotitlerowwithicon LaTeX命令。

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

    Added in version 8.1.0: Make \sphinxdotitlerow an alias to \sphinxdotitlerowwithicon.

    Added in version 8.1.0: 称号 topic , contents, 和 sidebar 指令也使用 \sphinxdotitlerow (they没有与它们相关联的默认图标）。

  • \sphinxtableofcontents: A wrapper (defined differently in sphinxhowto.cls and in sphinxmanual.cls) of standard \tableofcontents. The macro \sphinxtableofcontentshook is executed during its expansion right before \tableofcontents itself.

    在 1.5 版本发生变更: 以前，的含义 \tableofcontents 是由狮身克斯修改的。

    在 2.0 版本发生变更: Hard-coded redefinitions of \l@section and \l@subsection formerly done during loading of 'manual' docclass are now executed later via \sphinxtableofcontentshook. This macro is also executed by the 'howto' docclass, but defaults to empty with it.

    提示

    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: For 'manual' docclass, and if it is defined, it gets executed at end of \sphinxmaketitle, before the final \clearpage. Use either the 'maketitle' key or the 'preamble' key of latex_elements to add a custom definition of \sphinxbackoftitlepage.

    Added in version 1.8.3.

  • \sphinxcite: A wrapper of standard \cite for citation references.

的 \sphinxbox 命令

Added in version 6.2.0.

的 \sphinxbox[key=value,...]{inline text} 命令可用于“装箱”内联文本元素，具有中描述的所有可定制性 其他类似于css的内容 'sphinxsetup' 钥匙 . 这是一个LaTeX命令，带有一个可选参数，这是一个逗号分隔的key=Value对列表，例如 这个 sphinxsetup 配置设置 .这里是完整的密钥列表。 他们不使用任何前缀。

  • border-width ，

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

  • padding ，

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

  • border-radius ，

  • border-top-left-radius ， border-top-right-radius ， border-bottom-right-radius ， border-bottom-left-radius ，

  • box-shadow ，

  • border-TeXcolor ， background-TeXcolor ， box-shadow-TeXcolor ， TeXcolor ，

  • TeXextras ，

  • 和 addstrut 它是一个布尔键，即用作 addstrut=true ，或 addstrut 独自一人在哪里 =true 被省略，或 addstrut=false 。

This last key is specific to \sphinxbox and it means to add a \strut so that heights and depths are equalized across various instances on the same line with varying contents. The default is addstrut=false. The combination addstrut, padding-bottom=0pt, padding-top=1pt is often satisfactory.

Refer to 其他类似于css的内容 'sphinxsetup' 钥匙 for important syntax information regarding the other keys. The default configuration uses no shadow, a border-width of \fboxrule, a padding of \fboxsep, circular corners with radii \fboxsep and background and border colors as for the default rendering of code-blocks.

当一个 \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}}}
''',
}

A utility \newsphinxbox is provided to create a new boxing macro, say \foo which will act exactly like \sphinxbox but with a given extra configuration:

% 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}}

Boxes rendered with \foo obey as the ones using directly \sphinxbox the current configuration as set possibly mid-way in document via \sphinxboxsetup (from a raw LaTeX mark-up), the only difference is that they have an initial additional set of default extras.

In the above examples, you can probably use \renewcommand syntax if you prefer it to \protected\def (with [1] in place of #1 then).

环境

  • A figure may have an optional legend with arbitrary body elements: they are rendered in a sphinxlegend environment. The default definition issues \small, and ends with \par.

    Added in version 1.5.6: Formerly, the \small was hardcoded in LaTeX writer and the ending \par was lacking.

  • 与警告相关的环境：

    • sphinxnote ，

    • sphinxhint ，

    • sphinximportant ，

    • sphinxtip ，

    • sphinxwarning ，

    • sphinxcaution ，

    • sphinxattention ，

    • sphinxdanger ，

    • sphinxerror .

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

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

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

    Added in version 6.1.0.

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

  • 环境 todo 指令： sphinxtodo .它需要一个论点，即本地化 Todo (with末尾有一个结肠;默认渲染将删除该结肠并将本地化字符串放入其自己的彩色标题行中）。

    Added in version 7.4.0.

  • 的 topic , contents 和 sidebar 指令分别与 sphinxtopic , sphinxcontents ，而且 sphinxsidebar 环境.

    Added in version 1.4.2: 以前的代码被重构成允许分页符的环境。

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

    Added in version 8.1.0: 独立的环境（所有三个包装器围绕 sphinxShadowBox ）和单独的可定制性。

  • 文字块（通过 :: 或 code-block ），字面意思包括 (literalinclude ）使用 sphinxVerbatim 环境是 Verbatim 包装环境 fancyvrb.sty .它添加了顶部标题的处理和长行的包装，以及允许翻页的框架。桌子内部使用的环境是 sphinxVerbatimintable (it不绘制框架，但允许标题）。

    在 1.5 版本发生变更: Verbatim 与中的含义完全相同 fancyvrb.sty （也在姓名下） OriginalVerbatim ； sphinxVerbatimintable 在表格里使用。

    Added in version 1.5: 选项 verbatimwithframe ， verbatimwrapslines ， verbatimsep ， verbatimborder .

    Added in version 1.6.6: 支持 :emphasize-lines: 选项

    Added in version 1.6.6: 通过向用户展示LaTeX宏（例如），更容易自定义格式 \sphinxVerbatimHighlightLine .

  • 书目使用 sphinxthebibliography 和python模块索引以及常规索引都使用 sphinxtheindex ；这些环境是 thebibliography 分别是 theindex 由文档类（或包）提供的环境。

    在 1.5 版本发生变更: 以前，原始环境是由Sphinx改变的。

杂集

  • Every text paragraph in document body starts with \sphinxAtStartPar. Currently, this is used to insert a zero width horizontal skip which is a trick to allow TeX hyphenation of the first word of a paragraph in a narrow context (like a table cell). For 'lualatex' which does not need the trick, the \sphinxAtStartPar does nothing.

    Added in version 3.5.0.

  • 部分、小节、.标题设置使用 titlesec 的 \titleformat 命令

  • For the 'manual' docclass, the chapter headings can be customized using fncychap's commands \ChNameVar, \ChNumVar, \ChTitleVar. File sphinx.sty has custom re-definitions in case of fncychap option Bjarne.

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

  • The role directive allows to mark inline text with class arguments. This is handled in LaTeX output via the \DUrole dispatcher command as in Docutils. Object signatures also use \DUrole for some components, with one or two-letters class names as in HTML output.

    在 8.1.0 版本发生变更: When multiple classes are injected via a a custom role, the LaTeX output uses nested \DUrole's as in the Docutils documentation. Formerly it used a single \DUrole with comma separated classes, making the LaTeX customization more arduous.

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

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

    目前，类名称必须仅包含ASC字符，并避免LaTeX专用字符，例如 \ .

    Added in version 4.1.0.

提示

作为一项实验功能，如果您有一个名为 _templates/latex.tex.jinja 在您的项目中。

附加文件 longtable.tex.jinja , tabulary.tex.jinja 和 tabular.tex.jinja 可以添加到 _templates/ 配置表格渲染的某些方面（例如标题位置）。

Added in version 1.6: 目前，所有模板变量都不稳定且未记录。

在 7.4 版本发生变更: 添加了对 .jinja 文件扩展名，这是首选。旧文件名仍然受到支持。 (latex.tex_t , longtable.tex_t , tabulary.tex_t ，而且 tabular.tex_t )