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字符串字面量中,反斜杠必须被双写,以避免被解释为转义序列.或者,您可以像上面那样使用原始字符串.

The latex_elements 配置设置

一个字典,包含覆盖Sphinx通常放入生成的 .tex 文件中的LaTeX片段.它的 'sphinxsetup' 键将在:ref:单独描述 <latexsphinxsetup> .它还允许通过:dudir: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'

Added in version 1.5.

‘passoptionstopackages’

在前言中早期定位的字符串,旨在包含 \PassOptionsToPackage{options}{foo} 命令.

提示

它也可以用于在前言中非常早地加载 LaTeX 包.例如, fancybox 包与通过 'preamble' 键加载不兼容,必须更早加载.

默认:''

Added in version 1.4.

'babel'

“babel” 包含,默认 '\usepackage{babel}' （合适的文档语言字符串作为类选项传递,如果没有语言则使用 english ）.对于日语文档,默认值为空字符串.

使用XeLaTeX和LuaLaTeX,Sphinx配置LaTeX文档以使用 polyglossia ,但要注意的是,当前的 babel 在近年来改善了对Unicode引擎的支持,对于某些语言来说,可能更倾向于使用 babel 而不是 polyglossia .

提示

在修改了像这样的核心 LaTeX 键之后,在下一个 PDF 构建之前,请清理 LaTeX 构建目录,否则残留的辅助文件可能会破坏构建.

默认: '\usepackage{babel}' （用于日语文档）

在 1.5 版本发生变更: 对于 latex_engine 设置为 'xelatex' ,默认值为 '\usepackage{polyglossia} \setmainlanguage{<language>}' .

在 1.6 版本发生变更: ‘lualatex’ 使用与 ‘xelatex’``相同的默认设置

在 1.7.6 版本发生变更: 对于法语使用 'xelatex' （而不是 'lualatex' ）时,默认设置是使用 babel ,而不是 polyglossia .

在 7.4.0 版本发生变更: 针对法语使用 'lualatex' 的默认配置是使用 babel .

‘fontpkg’

字体包的包含.默认是:

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

对于 'xelatex' 和 'lualatex' ,默认是使用GNU FreeFont.

在 1.2 版本发生变更: 默认值为 '' ,当:confval:language 使用西里尔字母时.

在 2.0 版本发生变更: 包含一些字体替换命令,以帮助在使用 'pdflatex' 引擎的文档中偶尔支持希腊文或西里尔字母.

在 4.0.0 版本发生变更:

  • 在 2.0 中添加的字体替换命令已被移动到 'fontsubstitution' 键,因为它们在这里的存在使得用户自定义 'fontpkg' 的值变得复杂.

  • 默认字体设置已更改:它仍然使用 Times 和 Helvetica 的克隆作为衬线和无衬线字体,但通过更好、更完整的 TeX 字体和相关的 LaTeX 包.等宽字体已更改,以更好地与 Times 克隆相匹配.

'fncychap'

包含 “fncychap” 包（用于制作华丽的章节标题）,默认的 '\usepackage[Bjarne]{fncychap}' 用于英语文档（此选项是由 Sphinx 进行稍微自定义的）, '\usepackage[Sonny]{fncychap}' 用于国际化文档（因为 “Bjarne” 风格使用用英语拼写的数字）. 你可以尝试其他 “fncychap” 风格,如 “Lenny”, “Glenn”, “Conny”, “Rejne” 和 “Bjornstrup”. 你还可以将其设置为 '' 以禁用 fncychap.

默认:对于英语文档使用 '\usepackage[Bjarne]{fncychap}' ,对于国际化文档使用 '\usepackage[Sonny]{fncychap}' ,对于日文文档使用 '' .

‘preamble’`

附加的前言内容.可以将所有需要的宏移动到项目源目录中的某个文件 :file :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}'
}

在加载hyperref包和从Sphinx扩展加载的包之前,将加载指定的LaTeX包.

提示

如果您希望在 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” 包的包含.

默认: '\usepackage[utf8]{inputenc}' 当使用 pdflatex 时,否则为 '' .

备注

如果使用 utf8x 代替 utf8 ,则必须根据 utf8x 文档（在基于 TeXLive 的 TeX 安装中使用 texdoc ucs ）扩展 LaTeX 前言,并添加适当的 \PreloadUnicodePage{<number>} 命令.否则,PDF 中可能会出现意外且可能难以发现的问题（即不会导致构建崩溃）,特别是与超链接相关的问题.

即使采取了这些预防措施,通过 pdflatex 引擎生成的 PDF 也可能由于上游 LaTeX 与 utf8x 的不完全兼容而崩溃.例如,在与代码块相关的某些情况下,或者尝试包含文件名中包含 Unicode 字符的图像.实际上,自 2015 年起,上游 LaTeX 在 pdflatex 引擎下对 Unicode 的原生支持有所增强,并且与 utf8x 的不兼容性也越来越大.特别是,自 2019 年 10 月的 LaTeX 发布以来,文件名可以使用 Unicode 字符,甚至可以使用空格.在 Sphinx 层面,这意味着例如 image 和 figure 指令现在可以与 LaTeX 输出的 PDF 兼容这样的文件名.但是,如果使用 utf8x ,这就会失效.

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

‘cmappkg’

“cmap” 包的包含.

默认:'\usepackage{cmap}'

Added in version 1.2.

'fontenc'

将其默认的 '\usepackage[T1]{fontenc}' 自定义为:

  • ‘usepackage[X2,T1]{fontenc}’``如果您需要偶尔使用西里尔字母（физика частиц）,

  • '\\usepackage[LGR,T1]{fontenc}' if you need occasional Greek letters (Σωματιδιακή φυσική).

如果两者都需要,请使用 [LGR,X2,T1] .

注意

  • 请勿将此键用于除 'pdflatex' 以外的 latex_engine .

  • 如果希腊语是主要语言,请不要使用此键.自 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 时处理 << 和 >>``失败.

在 2.0 版本发生变更: 检测 LGR , T2A , X2 以触发对偶尔使用希腊字母或西里尔字母的支持 ( 'pdflatex' ).

在 2.3.0 版本发生变更: 'xelatex' executes \defaultfontfeatures[\rmfamily,\sffamily]{} in order to avoid contractions of -- into en-dash or transforms of straight quotes into curly ones in PDF (in non-literal text paragraphs) despite smartquotes being set to False.

‘fontsubstitution’（字体替换）

如果没有配置 'fontenc' 使用 LGR 或 X2 （或 T2A ）,则将被忽略.如果 'fontpkg' 键被配置为使用一些已知可用于 LGR 或 X2 编码的 TeX 字体,将其设置为空字符串.否则保持默认值.

忽略与 latex_engine 其他值,除了 'pdflatex' .

Added in version 4.0.0.

'textgreek'

为了支持偶尔使用的希腊字母.

当 latex_engine 设置为 'platex' , 'xelatex' 或 'lualatex' 时,忽略此项;对于 'pdflatex' ,则默认为空字符串或 '\usepackage{textalpha}' ,具体取决于 'fontenc' 键是否与 LGR 一起使用.只有专家级的 LaTeX 用户可能希望自定义此键.

它也可以用作 r'\usepackage{textalpha,alphabeta}' 来让 'pdflatex' 在 math 上下文中支持希腊Unicode输入.例如``:math:α```(U+03B1) 将呈现为 :math:alpha` .

默认:'\usepackage{textalpha}' 或者如果 fontenc 不包括 LGR 选项则为 '' .

Added in version 2.0.

'geometry'

“geometry” package 包含,默认定义为:

'\\usepackage{geometry}'

带有额外的 [dvipdfm] 用于日文文档. Sphinx LaTeX 样式文件执行:

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

可以通过相应的 ‘sphinxsetup’ 选项 进行自定义.

默认:'\usepackage{geometry}' (或 '\usepackage[dvipdfm]{geometry}' 用于日本文档)

Added in version 1.5.

在 1.5.2 版本发生变更: dvipdfm option if latex_engine is 'platex'.

Added in version 1.5.3: 该 ‘sphinxsetup’ 键用于边距 .

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

'hyperref'

“hyperref” 包的包含;同时加载 “hypcap” 包并执行 \urlstyle{same} .这一操作在加载 sphinx.sty 文件后进行,并在执行 'preamble' 键的内容之前进行.

注意

加载包 “hyperref” 和 “hypcap” 是必需的.

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

'maketitle'

“maketitle” 调用.如果您想生成不同样式的标题页,请重写此方法.

提示

如果键值设置为 r'\newcommand\sphinxbackoftitlepage{<附加材料>}\sphinxmaketitle' , 那么 <附加材料> 将会在封面背面排版（仅适用于 'manual' 文档类）.

默认:'\sphinxmaketitle'

在 1.8.3 版本发生变更: 原始的 \maketitle 来自文档类未被覆盖,因此可以作为该关键字的一部分在某些自定义设置中重用.

Added in version 1.8.3: \sphinxbackoftitlepage optional macro. It can also be defined inside 'preamble' key rather than this one.

‘releasename’

在标题页面上前缀 'release' 元素的值.对用于 latex_documents 的元组中的 title 和 author,它作为 LaTeX 标记插入.

默认值:'Release'

‘目录’}

“tableofcontents” 的调用.默认的 '\sphinxtableofcontents' 是未修改的 \tableofcontents 的包装器,用户加载的包可以自定义它.如果想生成不同的目录或在标题页与目录之间放置内容,请覆盖此设置.

默认值: '\sphinxtableofcontents'

在 1.5 版本发生变更: 以前, \tableofcontents 的含义被 Sphinx 修改.这导致了与专门修改它的包（如 “tocloft” 或 “etoc”）之间的不兼容性.

'transition'

用于显示过渡的命令.如果您想以不同的方式显示过渡,可以重写.

默认:``’

Added in version 1.2.

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

'makeindex'

在 \begin{document} 之前的最后一件事是 makeindex 调用.使用 '\usepackage[columns=1]{idxlayout}\makeindex' 可以让索引只使用一列.您可能需要安装 idxlayout LaTeX 包.

默认:'\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'

Customization of fancyvrb LaTeX package.

默认值为 '\fvset{fontsize=auto}' ,这意味着如果代码块出现在脚注中,字体大小将正确调整.如果你使用自定义字体,可能需要修改此设置: '\fvset{fontsize=\small}' ,如果等宽字体类似于Courier.

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

Added in version 1.8.

在 2.0 版本发生变更: 对于 'xelatex' 和 'lualatex' ,默认为 '\fvset{fontsize=\small}' ,因为这适应了 FreeFont 家族的相对宽度.

在 4.0.0 版本发生变更: 更改了 'pdflatex' 的默认值.之前使用的是 '\fvset{fontsize=\small}' .

在 4.1.0 版本发生变更: 已将中文文档的默认设置更改为 '\fvset{fontsize=\small,formatcom=\xeCJKVerbAddon}'

由于其他选项设置的键,因此不应被覆盖的是:

'文档类'``’类选项’``'标题'``’发行版’``'作者'

sphinxsetup 配置设置

Added in version 1.5.

The 'sphinxsetup' key of latex_elements provides a LaTeX-type customization interface:

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

LaTeX 对于布尔键的语法要求使用 小写 true 或 false ,例如 'sphinxsetup': "verbatimwrapslines=false" . 如果将布尔键设置为 true , =true 是可选的. 逗号和等号周围的空格会被忽略,LaTeX 宏内部的空格可能是重要的. 不要使用反引号/引号来包围字符串或数值.

The 'sphinxsetup' defaults to empty. If non-empty, it will be passed as argument to the \sphinxsetup macro inside the document preamble, like this:

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

可以通过 raw 指令直接在文档主体中插入 \sphinxsetup LaTeX 宏的使用:

.. raw:: latex

   \begingroup
   \sphinxsetup{%
      TitleColor=DarkGoldenrod,
      ... more comma separated key=value using LaTeX syntax ...
   }

All elements here will be under the influence of the raw ``\sphinxsetup``
settings.

.. raw:: latex

   \endgroup

From here on, the raw ``\sphinxsetup`` has no effect anymore.

这是用于特别为PDF输出样式化当前文档部分的技术. 实际使用的选项将在 development repository 的:file:doc/latex.rst 顶部找到.

上述示例中使用的颜色是通过将 svgnames 选项传递给 “xcolor” 包而可用的:

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

控制PDF中可折叠书签面板的深度.可以是一个数字（例如 3 ）或一个LaTeX节名称（例如 subsubsection ,即不带反斜杠）.有关详细信息,请参阅 hyperref LaTeX文档.

默认值:5

Added in version 4.0.0.

hmargin, vmargin

水平（对应垂直）边距的尺寸,通过 geometry 包的 hmargin （对应 vmargin ）选项传递.示例:

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

日本文档目前仅接受这些参数的单维格式.然后将适当的选项传递给 geometry 包,以使文本宽度设置为 zenkaku 宽度的精确倍数,文本高度设置为 baselineskip 的整数倍,并且尽量使边距最合适.

默认:1in (相当于 {1in,1in} )

提示

对于日语 'manual' 文档类,若字号为 11pt 或 12pt ,请使用 nomag 额外文档类选项（参见 :confval :latex_elements 的 'extraclassoptions' 键）或所谓的 TeX “真实” 单位.:

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

Added in version 1.5.3.

marginpar

The \marginparwidth LaTeX dimension. For Japanese documents, the value is modified to be the closest integer multiple of the zenkaku width.

默认值: 0.5in

Added in version 1.5.3.

mathnumsep

这默认为 math_numsep 所设置的字符串（不带引号!）,其默认值为 '.' .如果需要为 LaTeX 输出设置不同的值,请使用它.

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

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} 或 …

  • 或遵循包 xcolor 中 \colorlet 命令的语法,例如 VerbatimColor=red!10 或 red!50!green 或 -red!75 或 MyPreviouslyDefinedColor 等.有关此语法,请参考 xcolor 文档.

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

TitleColor

标题的颜色（通过使用”titlesec”包进行配置）.

默认:{rgb}{0.126,0.263,0.361}

InnerLinkColor

传递给 hyperref 作为 linkcolor 和 citecolor 值的颜色.

默认:{rgb}{0.208,0.374,0.486} .

OuterLinkColor

传递给 hyperref 作为 filecolor 、 menucolor 和 urlcolor 的值的颜色.

默认:{rgb}{0.216,0.439,0.388}

VerbatimColor

代码块的背景颜色为 code-block “}]} }

默认:{RGB}{242,242,242} (与 {gray}{0.95} 相同).

在 6.0.0 版本发生变更: 以前,它是 {rgb}{1,1,1} （白色）.

VerbatimBorderColor

框架颜色.

默认:{RGB}{32,32,32}

在 6.0.0 版本发生变更: 以前是 {rgb}{0,0,0} （黑色）.

VerbatimHighlightColor

突出行的颜色.

默认:{rgb}{0.878,1,1}

Added in version 1.6.6.

TableRowColorHeader

设置表格所有标题行的背景颜色.

只有当 latex_table_style 包含 'colorrows' 或者表格被分配了 colorrows 类时,它才会产生影响.对于 nocolorrows 类的表格,该设置将被忽略.

关于其他 'sphinxsetup' 键,它也可以通过 raw 指令插入的 \sphinxsetup{...} LaTeX 命令进行设置或修改,或者通过与 container class 关联的 LaTeX 环境使用这样的 \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 .另请参见 额外的 CSS 类似的 'sphinxsetup' 键 中的 pre_border-width .

默认:\fboxrule

重要

从8.1.0版本开始,可以单独为:dudir:topic 、contents_和:dudir:sidebar 指令设定样式,并且它们的默认值有所不同.请参见:ref:additionalcss .接下来的三个键作为遗留接口被保留,并未区分这三个指令.

shadowsep

此遗留选项同时设置 topic 、contents 和 sidebar 指令的填充（四个方向相同）.

shadowsize

这个遗留选项同时设置 topic 、contents 和 sidebar 指令的阴影宽度.

shadowrule

这个遗留选项同时为 topic 、contents 和 sidebar 指令设置边框宽度（四周相同）.

重要

在7.4.0版本中,所有的警告（不仅仅是危险类型）都使用了在5.1.0和6.2.0中添加的功能.所有的默认值都已经改变.

iconpackage

用于警告标题中图标的LaTeX包名称.默认为 fontawesome5 或回退到 fontawesome .如果两者都不可用,则选项值将自动默认为 none ,这意味着不尝试加载任何包.独立于此设置,可以通过 div.<type>_icon-title 键为每种警告类型关联任意LaTeX代码,这些键在 额外的 CSS 类似的 'sphinxsetup' 键 部分中描述.如果不使用这些键,Sphinx 将应用其默认的图标选择（如果 fontawesome{5,} 可用）或根本不绘制图标.请注意,如果使用回退的 fontawesome ,则 caution 和 danger 的共同图标将默认为 “bolt” 而不是 “radiation”,后者仅出现在 fontawesome5 中.

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

一些额外的 LaTeX 代码（例如 \bfseries 或 \footnotesize ）,将在内容开始时执行.

默认:空

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

|警告背景颜色|

警告框背景的背景颜色.

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

在 7.4.0 版本发生变更.

|警告边框|

警告框的宽度.有关允许单独配置每个边框宽度的键,请参见 额外的 CSS 类似的 'sphinxsetup' 键 .

默认: 1pt ,但 error 使用 1.25pt .

在 7.4.0 版本发生变更.

AtStartFootnote

在页底的脚注文本开始处,在脚注编号之后插入的LaTeX宏.

默认:\mbox{ }

BeforeFootnote

在脚注标记之前插入的LaTeX宏.默认情况下会去除它之前可能存在的空格（否则,TeX可能会在此插入换行符）.

默认: \leavevmode\unskip

Added in version 1.5.

HeaderFamily

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

额外的 CSS 类似的 'sphinxsetup' 键

Added in version 5.1.0: 对于 code-block 、topic 和 contents 指令,以及强类型的警示（warning 、error 等）.

Added in version 6.2.0: 同时,:dudir:note 、hint 、important 和 tip 的警告也可以以这种方式进行样式设计.使用列出的 任何 选项都会触发比默认使用的 LaTeX 代码更复杂的代码 ( sphinxheavybox 对比 sphinxlightbox ).设置新的 noteBgColor (或 hintBgColor , …) 也会对 note (或 hint , …) 触发使用 sphinxheavybox .

Added in version 7.4.0: 对于 所有 警告类型,默认配置确实设置了背景颜色（因此总是使用更丰富的 sphinxheavybox ）.

重要

此外,所有警告标题默认使用彩色行和图标进行样式设计,这些设计基于Sphinx自身文档的当前渲染,网址为https://www.sphinx-doc.org.CSS命名的键被添加以设置标题的前景色和背景色,以及图标的LaTeX代码.

Added in version 7.4.0: Customizability of the seealso and todo directives.

Added in version 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 or ...padding expect a single dimension: they can not be used so far with space separated dimensions.

  • ...top-right-radius et al. values may be either a single or two space separated dimensions.

  • 维度规范必须使用 TeX 单位,例如 pt 、 cm 或 in . px 单位被 pdflatex 和 lualatex 识别,但不被 xelatex 或 platex 识别.

  • 允许这种规范被称为”维度表达式”,例如 \fboxsep+2pt 或 0.5\baselineskip 是有效输入.这些表达式只会在排版时进行评估.不过,请小心在这些示例中使用 TeX 控制序列来加倍反斜杠或使用原始 Python 字符串作为 ‘sphinxsetup’ 键的值.

  • 作为一个规则,避免在键值中插入不必要的空格:特别是对于半径,输入如 2 pt 3pt 会导致 LaTeX 发生错误.注意 \fboxsep \fboxsep 在 LaTeX 中也不会被视为用空格分隔.你必须使用类似 {\fboxsep} \fboxsep 的形式.或者直接使用 3pt 3pt ,这在原则上是等效的并且更简单.

选项都是按照相似的模式命名的,该模式依赖于一个 前缀 ,然后是一个下划线,接着是属性名.

指令

选项前缀

LaTeX环境

代码块

pre

sphinxVerbatim

literalinclude

pre

sphinxVerbatim

主题

div.topic

sphinxtopic

内容

div.contents

sphinxcontents

侧边栏

div.sidebar

sphinxsidebar

注意

div.note

sphinxnote

警告

div.warning

sphinxwarning

进一步的警告类型 <type>

div.<type>

sphinx<type>

另请参阅

div.seealso

sphinxseealso

待办事项

div.todo

sphinxtodo

以下是这些选项及其常见的默认值.请将下面的 <prefix> 替换为上述说明的实际前缀.别忘了下划线分隔前缀和属性名称.

  • <prefix>_border-top-width,
    <prefix>_border-right-width,
    <prefix>_border-bottom-width,
    <prefix>_border-left-width,
    <prefix>_border-width. The latter can (currently) be only a single dimension which then sets all four others.

    默认情况下,这些维度都是相等的. 它们被设置为:

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

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

  • <prefix>_box-decoration-break can be set to either clone or slice and configures the behavior at page breaks. It defaults to slice for code-block (i.e. for <prefix>=pre) since 6.0.0. For other directives the default is clone.

  • <prefix>_padding-top,
    <prefix>_padding-right,
    <prefix>_padding-bottom,
    <prefix>_padding-left,
    <prefix>_padding. The latter can (currently) be only a single dimension which then sets all four others.

    默认值:

    • 所有四个 3pt 用于 代码块 ,

    • 6pt, 7pt, 6pt, 7pt for topic,

    • 10pt, 7pt, 12pt, 7pt for contents,

    • 6pt, 5.5pt, 6pt, 5.5pt for sidebar,

    • 6pt, 7pt, 6pt, 7pt for all “light” admonitions as well as the seealso and todo directives.

    • 6pt, 6.5pt, 6pt, 6.5pt for the strong admonition types except error which uses horizontal padding of 6.25pt.

    在 7.4.0 版本发生变更: 所有默认设置都已更改,除了 code-block .告示框的设置方式是左（或右）内边距加上左（或右）边框宽度始终加起来为 7.5pt ,因此在PDF的同一页面上,不同类型的告示框内容在垂直方向上保持良好的对齐.这仅仅是默认属性,而不是对用户选择可能性的限制.

    在 8.1.0 版本发生变更: 针对:dudir:topic 、contents_和:dudir:sidebar 分别设定默认值.

  • <prefix>_border-top-left-radius,
    <prefix>_border-top-right-radius,
    <prefix>_border-bottom-right-radius,
    <prefix>_border-bottom-left-radius,
    <prefix>_border-radius. This last key sets the first four to its assigned value. Each key value can be either a single, or two, dimensions which are then space separated.

    默认值:

    • 3pt for code-block (since 6.0.0) and all corners,

    • 8pt for all corners of topic,

    • 12pt for the bottom right corner of contents, others use 0pt,

    • 12pt for the top-left and bottom-right corners for sidebar, 0pt for top-right and bottom-left.

    • 所有半径设置为 5pt 用于 note 、hint 和 tip ,

    • 0pt, i.e. straight corners for all other directives.

    在 7.4.0 版本发生变更: topic 和 note -类的警告框具有（至少一个）圆角.

    在 8.1.0 版本发生变更: 针对:dudir:topic 、contents_和:dudir:sidebar 分别设定默认值.

    请参见上面的说明,关于LaTeX中包含空格的陷阱.

  • <prefix>_box-shadow is special in so far as it may be:

    • the none keyword,

    • 或一个单一维度（给定x偏移和y偏移）,

    • 或两个维度（以空格分隔）,

    • 或者两个维度后面跟随关键词 inset .

    x偏移量和y偏移量可以为负值.负的x偏移量意味着阴影在左侧.无论偏移量是正还是负,阴影都会延伸到页面边距.

    默认值为 none ,*除了* contents 指令使用 4pt 4pt .

    在 8.1.0 版本发生变更: 默认情况下,:dudir:topic 和 sidebar 不会有阴影.

  • <prefix>_border-TeXcolor,
    <prefix>_background-TeXcolor,
    <prefix>_box-shadow-TeXcolor,
    <prefix>_TeXcolor. These are colors.

    从6.0.0版本开始,:rst:dir:code-block 的边框和背景颜色默认分别为 {RGB}{32,32,32} （即 {HTML}{202020} ）和 {RGB}{242,242,242} （即 {gray}{0.95} 或 {HTML}{F2F2F2} ）.

    在7.4.0版本中,其他指令获取了非黑白的默认边框和背景颜色.这里使用的是 xcolor 的十六进制表示法（始终需要6个十六进制数字）:

    • {HTML}{F7F7F7} serves as background color to all.

    • {HTML}{86989B} is border color of light admonitions (inclusive of seealso and todo) as well as of topic, contents and sidebar directives.

    • {HTML}{940000} is border color of warning-type admonitions, except error which uses {HTML}{B40000}.

    默认情况下,唯一显示阴影的指令是 contents 和 sidebar .前者的阴影颜色为 {HTML}{6C6C6C} ,后者的阴影颜色为 {HTML}{9EACAF} .

    The <prefix>_TeXcolor stands for the CSS property “color”, i.e. it influences the text color of the contents. As for the three other options, the naming TeXcolor is to stress that the input syntax is the TeX one for colors not an HTML/CSS one. If package xcolor is available in the LaTeX installation, one can use directly named colors as key values. Consider passing options such as dvipsnames, svgnames or x11names to xcolor via 'passoptionstopackages' key of latex_elements.

    如果设置了 <prefix>_TeXcolor ,则在指令内容的开头插入 \color 命令;对于警告,这将在复制警告类型的标题之后发生.

  • <prefix>_TeXextras: if set, its value must be some LaTeX command or commands, for example \itshape. These commands will be inserted at the start of the contents; for admonitions, this happens after the heading which reproduces the admonition type.

以下的键,用于警告,:dudir:topic 、contents_和:dudir:sidebar ,这三者都在7.4.0中添加（而后三者在8.1.0中添加）.

  • div.<type>_title-background-TeXcolor: the background color for the title.

    重要

    彩色标题行是根据Sphinx对各种 \sphinxstyle<type>title 命令的默认定义生成的,这些命令使用 \sphinxdotitlerow LaTeX 命令.请参见 宏 .

  • div.<type>_title-foreground-TeXcolor: the color to be used for the icon (it applies only to the icon, not to the title of the admonition).

  • div.<type>_title-icon: the LaTeX code responsible for producing the icon. For example, the default for note is div.note_title-icon=\faIcon{info-circle}. This uses a command from the LaTeX fontawesome5 package, which is loaded automatically if available.

    如果既没有找到 fontawesome5 也没有找到后备的 fontawesome (其关联命令为 \faicon , 而不是 \faIcon ),或者如果 iconpackage 键在 ‘sphinxsetup’ 中被设置为加载其他用户选择的包,或根本没有包,那么所有的 title-icons 默认将变为空的 LaTeX 代码.用户可以利用这个接口将图标（或其他任何内容）注入到 PDF 输出中.

备注

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

    在 6.2.0 版本发生变更: 以前,只有 code-block 才这样.所有其他指令的默认值仍然是 clone ,但这在 7.0.0 版本中可能会发生改变.

  • 圆角框的角可能是椭圆形的.

    在 6.2.0 版本发生变更: 以前,只支持圆形的圆角,并且一个圆角会强制整个框架使用来自 <prefix>_border-width 的相同固定宽度.

  • 插入阴影与圆角不兼容.如果同时指定了两者,插入阴影将被忽略.

    在 6.2.0 版本发生变更: 以前,如果指定了内凹阴影,则会忽略圆角的设置.

  • <prefix>_TeXcolor and <prefix>_TeXextras are new with 6.2.0.

    在使用 code-block 的情况下,其实用性是值得怀疑的:

    • pre_TeXcolor will influence only the few non-Pygments highlighted tokens; it does color the line numbers, but if one wants to color only them one has to go through the fancyvrb interface.

    • 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'…

    考虑这些选项为实验性的,某些实现细节可能会发生变化.例如,如果 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 工具链转换为 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] with larger brackets, see source

    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 which is used for one-parameter-per-line signatures (see maximum_signature_line_length). It defaults to \texttt{,} to make these end-of-line separators more distinctive.

    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}) (with a space upfront)

    \sphinxstyleindexpageref

    , \pageref{#1}

    \sphinxstyleindexpagemain

    \textbf{#1}

    \sphinxstyleindexlettergroup

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

    \sphinxstyleindexlettergroupDefault

    check source, too long for here

    \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: 这些宏以前被硬编码为不可自定义的 \texttt 、 \emph 等…

    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 now detects automatically if an icon is associated or not with the rendered element used as first argument.

    Added in version 8.1.0: 将 \sphinxdotitlerow 设为 \sphinxdotitlerowwithicon 的别名.

    Added in version 8.1.0: 标题 topic 、内容 和 sidebar 指令也使用 \sphinxdotitlerow 进行样式设置（它们没有默认的图标与之关联）.

  • \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 的含义被 Sphinx 修改过.

    在 2.0 版本发生变更: 在加载 'manual' 文档类时,硬编码的 \l@section 和 \l@subsection 重新定义现在通过 \sphinxtableofcontentshook 在稍后执行.这个宏也被 'howto' 文档类执行,但在该文档类下默认为空.

    提示

    如果在前言中添加了 tocloft 包的加载,还需要在前言中添加 \renewcommand\sphinxtableofcontentshook{} ,否则会重置 \l@section 和 \l@subsection ,取消 tocloft 的自定义配置.

  • \sphinxmaketitle: Used as the default setting of the 'maketitle' latex_elements key. Defined in the class files sphinxmanual.cls and sphinxhowto.cls.

    在 1.8.3 版本发生变更: 以前,Sphinx 修改了 LaTeX 文档类中的 \maketitle .

  • \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.

The \sphinxbox command

Added in version 6.2.0.

The \sphinxbox[key=value,...]{inline text} command can be used to “box” inline text elements with all the customizability which has been described in 额外的 CSS 类似的 'sphinxsetup' 键. It is a LaTeX command with one optional argument, which is a comma-separated list of key=value pairs, as for sphinxsetup 配置设置. Here is the complete list of keys. They don’t use any prefix.

  • 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 的用法嵌套在另一个用法中时,它会忽略外层的选项:首先,它将所有选项重置为其默认状态,即在应用外层框选项之前的状态,然后应用其自己的特定选项.

可以通过命令 \sphinxboxsetup{key=value,...} 修改这些默认值.效果是累积的,如果多次使用此命令.这里的选项是一个必需的参数,因此需要放在花括号内,而不是方括号中.

以下是一些使用示例:

latex_elements = {
    'preamble': r'''
% modify globally the defaults
\sphinxboxsetup{border-width=2pt,%
                border-radius=4pt,%
                background-TeXcolor=yellow!20}
% configure some styling element with some extra specific options:
\protected\def\sphinxkeyboard#1{\sphinxbox[border-TeXcolor=green]{\sphinxcode{#1}}}
''',
}

一个实用工具 \newsphinxbox 被提供用于创建一个新的框宏,比如 \foo ,它的作用与 \sphinxbox 完全相同,但具有特定的额外配置:

% the specific options to \foo are within brackets
\newsphinxbox[border-radius=0pt, box-shadow=2pt 2pt]{\foo}
% then use this \foo, possibly with some extra options still:
\protected\def\sphinxguilabel#1{\foo{#1}}
\protected\def\sphinxmenuselection#1{\foo[box-shadow-TeXcolor=gray]{#1}}

使用 \foo 渲染的框遵循与直接使用 \sphinxbox 相同的当前配置,该配置可以在文档中途通过 \sphinxboxsetup （来自 raw LaTeX 标记）设置,唯一的区别是它们有一组额外的默认选项.

在上述示例中,如果您更喜欢使用 \renewcommand 语法,那么可以使用它来替代 \protected\def （此时用 [1] 代替 #1 ）.

环境

  • A figure 可以具有一个可选的图例,包含任意的主体元素:它们在 sphinxlegend 环境中渲染.默认定义使用 \small ,并以 \par 结束.

    Added in version 1.5.6: 以前, \small 在 LaTeX 编写器中是硬编码的,并且缺少结尾的 \par .

  • 与警告相关的环境:

    • sphinxnote,

    • sphinxhint,

    • sphinximportant,

    • sphinxtip,

    • sphinxwarning,

    • sphinxcaution,

    • sphinxattention,

    • sphinxdanger,

    • sphinxerror.

    它们可以单独 \renewenvironment ,并且必须使用一个参数进行定义（例如,这是通知的标题,对于 warning 指令,英语文档语言时可以使用 Warning: ）.它们的默认定义使用 sphinxheavybox*（适用于最后五个）或 *sphinxlightbox 环境,配置为使用特定于每种类型的参数（颜色、边框厚度）,可以通过 'sphinxsetup' 字符串进行设置.

    在 1.5 版本发生变更: 使用公共环境名称,参数的可定制性分开,例如 noteBorderColor , noteborder , warningBgColor , warningBorderColor , warningborder ,…

  • 为:rst:dir:seealso 指令准备的环境: sphinxseealso .它接受一个参数,该参数将是本地化字符串 See also ,后面跟随一个冒号.

    Added in version 6.1.0.

    在 6.2.0 版本发生变更: 冒号成为标记的一部分,而不是由环境插入,以便与一般处理的注意事项保持一致.

  • 环境用于 todo 指令:sphinxtodo .它接受一个参数,即 Todo 的本地化（以冒号结尾;默认渲染将移除该冒号,并将本地化字符串放在其自己的有色标题行中）.

    Added in version 7.4.0.

  • The topic, contents and sidebar directives are associated with respectively sphinxtopic, sphinxcontents, and sphinxsidebar environments.

    Added in version 1.4.2: 以前的代码重构为允许分页的环境.

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

    Added in version 8.1.0: 分开的环境（所有三个围绕 sphinxShadowBox 的封装）和独立的可定制性.

  • 字面块（通过 :: 或 code-block ）、字面包含 (literalinclude ) 是使用 sphinxVerbatim 环境实现的,它是来自 fancyvrb.sty 包的 Verbatim 环境的包装.它增加了对顶部标题的处理、对长行的换行,以及一个允许分页的框架.在表格内部,使用的环境是 sphinxVerbatimintable （它不绘制框架,但允许有标题）.

    在 1.5 版本发生变更: Verbatim keeps exact same meaning as in fancyvrb.sty (also under the name OriginalVerbatim); sphinxVerbatimintable is used inside tables.

    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 修改过.

杂项

  • 文档主体中的每个文本段落都以 \sphinxAtStartPar 开头.目前,这用于插入一个零宽水平跳过,这是允许TeX在狭窄上下文（如表格单元格）中对段落的第一个单词进行连字的技巧.对于不需要此技巧的 'lualatex' , \sphinxAtStartPar 不执行任何操作.

    Added in version 3.5.0.

  • 该章节、子章节等标题是使用 titlesec 的 \titleformat 命令设置的.

  • 对于 'manual' 文档类,可以使用 fncychap 的命令 \ChNameVar , \ChNumVar , \ChTitleVar 自定义章节标题.文件 sphinx.sty 在使用 fncychap 选项 Bjarne 时有自定义的重新定义.

    在 1.5 版本发生变更: 以前,*fncychap* 与除了 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 版本发生变更: 当通过自定义角色注入多个类时,LaTeX 输出使用嵌套的 \DUrole ,如 Docutils 文档 中所述.之前,它使用单个 \DUrole ,类之间用逗号分隔,这使得 LaTeX 自定义变得更加繁琐.

  • Docutils 容器 指令在 LaTeX 输出中受到支持:要让名称为 foo 的容器类通过 LaTeX 影响最终的 PDF,只需在前言中定义一个环境 sphinxclassfoo . 一个简单的示例是:

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

    目前类名称必须仅包含 ASCII 字符,并避免包含对 LaTeX 特殊的字符,如 \ .

    Added in version 4.1.0.

提示

作为一项实验性功能,如果您的项目中有一个名为 _templates/latex.tex.jinja 的文件,Sphinx可以使用用户定义的模板文件来生成LaTeX源代码.

附加文件 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 )