LaTeX customization¶
The latex target does not benefit from pre-prepared themes like the html target does (see HTML theming support).
Basic customization¶
It is available from conf.py
via usage of the Options for LaTeX output as described in The build configuration file (backslashes must be doubled in Python string literals to reach latex.) For example:
# inside conf.py
latex_engine = 'xelatex'
latex_elements = {
'fontenc': '\\usepackage{fontspec}',
'fontpkg': '''\
\\setmainfont{DejaVu Serif}
\\setsansfont{DejaVu Sans}
\\setmonofont{DejaVu Sans Mono}''',
'geometry': '\\usepackage[vmargin=2.5cm, hmargin=3cm]{geometry}',
'preamble': '''\
\\usepackage[titles]{tocloft}
\\cftsetpnumwidth {1.25cm}\\cftsetrmarg{1.5cm}
\\setlength{\\cftchapnumwidth}{0.75cm}
\\setlength{\\cftsecindent}{\\cftchapnumwidth}
\\setlength{\\cftsecnumwidth}{1.25cm}''',
'fncychap': '\\usepackage[Bjornstrup]{fncychap}',
'printindex': '\\footnotesize\\raggedright\\printindex',
}
latex_show_urls = 'footnote'
More advanced customization will be obtained via insertion into the LaTeX preamble of relevant \renewcommand
, \renewenvironment
, \setlength
, or \definecolor
commands. The 'preamble'
key of latex_elements
will serve for inserting these commands. If they are numerous, it may prove more convenient to assemble them into a specialized file mystyle.tex
and then use:
'preamble': r'\makeatletter\input{mystyle.tex}\makeatother',
or, better, to set up a style file mystyle.sty
which can then be loaded via:
'preamble': r'\usepackage{mystyle}',
The build configuration file file for the project needs to have its variable latex_additional_files
appropriately configured, for example:
latex_additional_files = ["mystyle.sty"]
The Sphinx LaTeX style package options¶
The 'sphinxsetup'
key to latex_elements
provides a more convenient interface to various style parameters. It is a comma separated string of key=value
instructions:
key1=value1,key2=value2, ...
- if a key is repeated, it is its last occurence which counts,
- spaces around the commas and equal signs are ignored.
If non-empty, it will be passed as argument to the \sphinxsetup
command:
\usepackage{sphinx}
\sphinxsetup{key1=value1,key2=value2,...}
New in version 1.5.
Note
Most options described next could also have been positioned as
sphinx.sty
package options. But for those where the key value contains some LaTeX code the use of\sphinxsetup
is mandatory. Hence the whole'sphinxsetup'
string is passed as argument to\sphinxsetup
.As an alternative to the
'sphinxsetup'
key, it is possibly to insert explicitely the\\sphinxsetup{key=value,..}
inside the'preamble'
key. It is even possible to use the\sphinxsetup
in the body of the document, via theraw
directive, to modify dynamically the option values: this is actually what we did for the duration of this chapter for the PDF output, which is styled using:verbatimwithframe=false, VerbatimColor={named}{OldLace}, TitleColor={named}{DarkGoldenrod}, hintBorderColor={named}{LightCoral}, attentionBgColor={named}{LightPink}, attentionborder=3pt, attentionBorderColor={named}{Crimson}, noteBorderColor={named}{Olive}, noteborder=2pt, cautionBorderColor={named}{Cyan}, cautionBgColor={named}{LightCyan}, cautionborder=3pt
and with the
svgnames
option having been passed to “xcolor” package:latex_elements = { 'passoptionstopackages': r'\PassOptionsToPackage{svgnames}{xcolor}', }
Here are the currently available options together with their default values.
Caution
These options correspond to what has been so far the default LaTeX rendering by Sphinx; if in future Sphinx offers various themes for LaTeX, the interface may change.
verbatimwithframe
default
true
. Boolean to specify ifcode-block
s and literal includes are framed. Setting it tofalse
does not deactivate use of package “framed”, because it is still in use for the optional background colour (see below).Attention
LaTeX requires
true
orfalse
to be specified in lowercase.verbatimwrapslines
- default
true
. Tells whether long lines incode-block
s should be wrapped. inlineliteralwraps
default
true
. Allows linebreaks inside inline literals: but extra potential break-points (additionally to those allowed by LaTeX at spaces or for hyphenation) are currently inserted only after the characters. , ; ? ! /
. Due to TeX internals, white space in the line will be stretched (or shrinked) in order to accomodate the linebreak.New in version 1.5: set this option to
false
to recover former behaviour.verbatimvisiblespace
- default
\textcolor{red}{\textvisiblespace}
. When a long code line is split, space characters located at end of the line before the break are displayed using this code. verbatimcontinued
The default is:
\makebox[2\fontcharwd\font`\x][r]{\textcolor{red}{\tiny$\hookrightarrow$}}
It is printed at start of continuation lines. This rather formidable expression reserves twice the width of a typical character in the current (monospaced) font and puts there a small red hook pointing to the right.
Changed in version 1.5: The breaking of long code lines was introduced at 1.4.2. The space reserved to the continuation symbol was changed at 1.5 to obey the current font characteristics (this was needed as Sphinx 1.5 LaTeX allows code-blocks in footnotes which use a smaller font size).
Hint
This specification gives the same spacing as before 1.5:
\normalfont\normalsize\makebox[3ex][r]{\textcolor{red}{\tiny$\hookrightarrow$}
TitleColor
- default
{rgb}{0.126,0.263,0.361}
. The colour for titles (as configured via use of package “titlesec”.) It must obey the syntax of the\definecolor
command. Check the documentation of packagescolor
orxcolor
. InnerLinkColor
- default
{rgb}{0.208,0.374,0.486}
. A colour passed tohyperref
as value oflinkcolor
andcitecolor
. OuterLinkColor
- default
{rgb}{0.216,0.439,0.388}
. A colour passed tohyperref
as value offilecolor
,menucolor
, andurlcolor
. VerbatimColor
- default
{rgb}{1,1,1}
. The background colour forcode-block
s. The default is white. VerbatimBorderColor
- default
{rgb}{0,0,0}
. The frame color, defaults to black. verbatimsep
- default
\fboxsep
. The separation between code lines and the frame. verbatimborder
- default
\fboxrule
. The width of the frame aroundcode-block
s. shadowsep
- default
5pt
. The separation between contents and frame for contents and topic boxes. shadowsize
- default
4pt
. The width of the lateral “shadow” to the right. shadowrule
- default
\fboxrule
. The width of the frame around topic boxes. noteBorderColor
default
{rgb}{0,0,0}
. The colour for the two horizontal rules used by Sphinx in LaTeX for styling a note admonition. Defaults to black.Note
The actual name of the colour as declared to “color” or “xcolor” is
sphinxnoteBorderColor
. The same “sphinx” prefix applies to all colours for notices and admonitions.hintBorderColor
- default
{rgb}{0,0,0}
. id. importantBorderColor
- default
{rgb}{0,0,0}
. id. tipBorderColor
- default
{rgb}{0,0,0}
. id. noteborder
- default
0.5pt
. The width of the two horizontal rules. hintborder
- default
0.5pt
. id. importantborder
- default
0.5pt
. id. tipborder
- default
0.5pt
. id. warningBorderColor
- default
{rgb}{0,0,0}
. The colour of the frame for warning type admonitions. Defaults to black. cautionBorderColor
- default
{rgb}{0,0,0}
. id. attentionBorderColor
- default
{rgb}{0,0,0}
. id. dangerBorderColor
- default
{rgb}{0,0,0}
. id. errorBorderColor
- default
{rgb}{0,0,0}
. id. warningBgColor
- default
{rgb}{1,1,1}
. The background colour for warning type admonition, defaults to white. cautionBgColor
- default
{rgb}{1,1,1}
. id. attentionBgColor
- default
{rgb}{1,1,1}
. id. dangerBgColor
- default
{rgb}{1,1,1}
. id. errorBgColor
- default
{rgb}{1,1,1}
. id. warningborder
- default
1pt
. The width of the frame. cautionborder
- default
1pt
. id. attentionborder
- default
1pt
. id. dangerborder
- default
1pt
. id. errorborder
- default
1pt
. id. AtStartFootnote
- default
\mbox{ }
. LaTeX macros inserted at the start of the footnote text at bottom of page, after the footnote number. BeforeFootnote
default
\leavevmode\unskip
. LaTeX macros inserted before the footnote mark. The default removes possible space before it.It can be set to empty (
BeforeFootnote={},
) to recover the earlier behaviour of Sphinx, or alternatively contain a\nobreak\space
or a\thinspace
after the\unskip
to insert some chosen (non-breakable) space.New in version 1.5: formerly, footnotes from explicit mark-up were preceded by a space (hence a linebreak there was possible), but automatically generated footnotes had no such space.
HeaderFamily
- default
\sffamily\bfseries
. Sets the font used by headings.
As seen above, key values may even be used for LaTeX commands. But don’t forget to double the backslashes if not using “raw” Python strings.
The LaTeX environments defined by Sphinx¶
Let us now list some macros from the package file sphinx.sty
and class file sphinxhowto.cls
or sphinxmanual.cls
, which can be entirely redefined, if desired.
text styling commands (they have one argument):
\sphinx<foo>
with<foo>
being one ofstrong
,bfcode
,email
,tablecontinued
,titleref
,menuselection
,accelerator
,crossref
,termref
,optional
. By default and for backwards compatibility the\sphinx<foo>
expands to\<foo>
hence the user can choose to customize rather the latter (the non-prefixed macros will be left undefined if optionlatex_keep_old_macro_names
is set toFalse
inconf.py
.)Changed in version 1.4.5: use of
\sphinx
prefixed macro names to limit possibilities of conflict with user added packages: iflatex_keep_old_macro_names
is set toFalse
inconf.py
only the prefixed names are defined.more text styling commands:
\sphinxstyle<bar>
with<bar>
one ofindexentry
,indexextra
,indexpageref
,topictitle
,sidebartitle
,othertitle
,sidebarsubtitle
,thead
,emphasis
,literalemphasis
,strong
,literalstrong
,abbreviation
,literalintitle
.New in version 1.5: the new macros are wrappers of the formerly hard-coded
\texttt
,\emph
, ... The default definitions can be found insphinx.sty
.paragraph level environments: for each admonition type
<foo>
, the used environment is namedsphinx<foo>
. They may be\renewenvironment
‘d individually, and must then be defined with one argument (it is the heading of the notice, for exampleWarning:
for warning directive, if English is the document language). Their default definitions use either the sphinxheavybox (for the first listed directives) or the sphinxlightbox environments, configured to use the parameters (colours, border thickness) specific to each type, which can be set via'sphinxsetup'
string.Changed in version 1.5: use of public environment names, separate customizability of the parameters.
the contents directive (with
:local:
option) and the topic directive are implemented by environmentsphinxShadowBox
. See above for the three dimensions associated with it.Changed in version 1.5: use of public names for the three lengths. The environment itself was redefined to allow page breaks at release 1.4.2.
the literal blocks (
code-block
directives, etc ...), are implemented usingsphinxVerbatim
environment which is a wrapper ofVerbatim
environment from packagefancyvrb.sty
. It adds the handling of the top caption and the wrapping of long lines, and a frame which allows pagebreaks. Inside tables the used environment issphinxVerbatimintable
(it does not draw a frame, but allows a caption).Changed in version 1.5:
Verbatim
keeps exact same meaning as infancyvrb.sty
(meaning which is the one ofOriginalVerbatim
too), and custom one is calledsphinxVerbatim
. Also, earlier version of Sphinx usedOriginalVerbatim
inside tables (captions were lost, long code lines were not wrapped), it now uses theresphinxVerbatimintable
.New in version 1.5: the two customizable lengths, the
sphinxVerbatimintable
, the boolean toggles described above.by default the Sphinx style file
sphinx.sty
includes the command\fvset{fontsize=\small}
as part of its configuration offancyvrb.sty
. The user may override this for example via\fvset{fontsize=auto}
which will use for listings the ambient font size. Refer tofancyvrb.sty
‘s documentation for further keys.New in version 1.5: formerly, the use of
\small
for code listings was not customizable.the section, subsection, ... headings are set using titlesec‘s
\titleformat
command. Checksphinx.sty
for the definitions.for the
'sphinxmanual'
class (corresponding to the fifth element oflatex_documents
being set to'manual'
), the chapter headings can be customized using fncychap‘s commands\ChNameVar
,\ChNumVar
,\ChTitleVar
. Checksphinx.sty
for the default definitions. They are applied only if fncychap is loaded with optionBjarne
. It is also possible to use an empty'fncychap'
key, and use the titlesec\titleformat
command to style the chapter titles.Changed in version 1.5: formerly, use of fncychap with other styles than
Bjarne
was dysfunctional.the table of contents is typeset via
\sphinxtableofcontents
which is a wrapper (whose definition can be found insphinxhowto.cls
or insphinxmanual.cls
) of standard\tableofcontents
.Changed in version 1.5: formerly, the meaning of
\tableofcontents
was modified by Sphinx.the bibliography and Python Module index are typeset respectively within environments
sphinxthebibliography
andsphinxtheindex
, which are simple wrappers of the non-modifiedthebibliography
andtheindex
environments.Changed in version 1.5: formerly, the original environments were modified by Sphinx.
the list is not exhaustive: refer to
sphinx.sty
for more.
Hint
As an experimental feature, Sphinx can use user-defined template file for LaTeX source if you have a file named _templates/latex.tex_t
on your project. Now all template variables are unstable and undocumented. They will be changed in future version.
New in version 1.5.