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 packagefontspec
(included via 'fontenc') are used to set up the OpenType fonts GNU FreeSerif, FreeSans, and FreeMono (scaled with ratio0.9
) as document fonts.在 1.2 版本发生变更: 默认为
''
当language
使用西里尔文脚本。在 2.0 版本发生变更: 将一些字体替换命令转换为帮助支持文档中偶尔出现的希腊文或西里尔文,
'pdflatex'
发动机在4.0.0,这些命令被移至'fontsubstitution'
钥匙在 4.0.0 版本发生变更: 默认字体设置已更改。 如上所示,它仍然使用Times和Helvetica克隆来进行衬线和无衬线,但通过更好、更完整的TeX字体和相关的LaTeX包。 单层字体已更改,以更好地匹配《泰晤士报》克隆版。
'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年开始,上游的 Latexpdflatex
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 withsmartquotes
set toFalse
).'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}'
orr'\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}
. Withr'\usepackage[columns=1]{idxlayout}\makeindex'
the index will use only one column. You may have to installidxlayout
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, user'\def\twocolumn[#1]{#1}\printindex'
(this trick may fail if using a custom document class; then try theidxlayout
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 tor'\fvset{fontsize=\small}'
if it is Courier-like (for Unicode engines, it is recommended to use rather theScale
interface of\setmonofont
LaTeX command fromfontspec
).默认:
r'\fvset{fontsize=auto}'
Added in version 1.8.
在 2.0 版本发生变更: For
'xelatex'
and'lualatex'
defaults tor'\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 usingr'\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'
点大小的DocClass11pt
或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
shadowsize
shadowrule
重要
7.4.0中的所有警告(不仅仅是警告类型)都使用5.1.0和6.2.0中添加的可能性。 所有默认设置均已更改。
iconpackage
用于在警告标题中呈现图标的LaTeX包的名称。 其默认值动态设置为
fontawesome6
,fontawesome5
,或者fontawesome
,或者none
,具体取决于使用的LaTeX安装中是否存在具有这些名称的包。 LaTeX代码将使用\faIcon
命令if withfontawesome6/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代码。
也许将来这些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
or0.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 directly3pt 3pt
which is a priori equivalent and simpler.
所有选项都以类似的模式命名,该模式取决于 prefix
,然后是下划线,然后是属性名称。
指令 |
选项前缀 |
Latex 环境 |
---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
进一步的警告类型 |
|
|
|
|
|
|
|
下面是这些选项及其常见的默认设置。在下面替换 <prefix>
通过如上所述的实际前缀。不要忘记用下划线将前缀与属性名称隔开。
<prefix>_border-top-width
,<prefix>_border-right-width
,<prefix>_border-bottom-width
,<prefix>_border-left-width
,<prefix>_border-width
。后者可能(目前)只是一个 single 维度,然后设置所有其他四个维度。默认情况下,所有这些尺寸都相等。它们设置为:
<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
,6.5pt
,6pt
,6.5pt
对于强烈的告诫类型,除了 error 它使用水平填充6.25pt
.
在 7.4.0 版本发生变更: 所有默认设置均已更改,但
code-block
. 警告的设置是为了使左(或右)填充加上左(或右)边框宽度相加始终为7.5pt
,因此PDF中同一页面上的警告类型的内容垂直对齐。 这只是默认值的属性,而不是对用户可能选择的约束。<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
用于右上角和左下角。0pt
,即所有其他指令的锐角。
参见上面关于LaTeX中带有空格的陷阱的备注。
<prefix>_box-shadow
是特殊的,因为它可能是:这个
none
关键字,或单一维度(给出x偏移和y偏移两者),
或二维(由空格隔开),
或后跟关键字的两个维度
inset
。
x偏置和y偏置可能为负。 负x偏置意味着阴影在左侧。 无论抵消是正还是负,阴影都会延伸到页面页边。
The default is
none
except for the contents directive which uses4pt 4pt
.<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 eitherfontawesome6
orfontawesome5
LaTeX package is available on your system). For example the default for note isdiv.note_title-icon=\faIcon{info-circle}
withfontawesome5
anddiv.note_title-icon=\faIcon{circle-info}
withfontawesome6
(which is used automatically if available). If your system only provides thefontawesome
package (automatically detected) use its command\faicon
rather in order to modify the choice of icons. Theiconpackage
key can be used to use some other package providing icons, use then the commands suitable to that package as values of thediv.<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 tor'\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 (seemaximum_signature_line_length
) and defaults to\texttt{,}
.Signatures of Python functions are rendered as
name<space>(parameters)
orname<space>[type parameters]<space>(parameters)
(see PEP 695) where the length of<space>
is set to0pt
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
.\sphinxtableofcontents
: A wrapper (defined differently insphinxhowto.cls
and insphinxmanual.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
cancellingtocloft
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 oflatex_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
. Filesphinx.sty
has custom re-definitions in case of fncychap optionBjarne
.在 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
)