Customizing the rendering¶

LaTeX template¶

The LaTeX template is defined in file conf.py:

# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title, author, documentclass [howto/manual]).
latex_documents = [
    ('Index', 'myext.tex', u'My Extension Documentation',
     u'Xavier Perseguers', 'manual'),
]

In this example, the document class within conf.py is manual (last tupple of latex_documents). This means that after Sphinx has automatically added the prefix sphinx during compilation, the actual document class as seen by LaTeX is sphinxmanual:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

% Generated by Sphinx.
\def\sphinxdocclass{report}
\documentclass[a4paper,10pt,english]{sphinxmanual}
\usepackage[utf8]{inputenc}
\DeclareUnicodeCharacter{00A0}{\nobreakspace}
\usepackage{cmap}
\usepackage[T1]{fontenc}
\usepackage{babel}
\usepackage{times}
\usepackage[Bjarne]{fncychap}
\usepackage{longtable}
\usepackage{sphinx}
\usepackage{multirow}

\title{My Extension Documentation}
\date{2013-06-30 22:25}
\release{1.0.0}
\author{Xavier Perseguers}

Sphinx provides two document classes:

• manual that is, sphinxmanual, extending the real LaTeX document class report (by default two-side with full title page);
• howto that is, sphinxhowto, extending the real LaTeX document class article (by default one-side). "howto" documents will not get appendices. Also, howtos will have a simpler title page.

Both class files (sphinxmanual.cls and sphinxhowto.cls) are copied to directory build/latex/ during rendering.

After playing with the various options to customize the rendering, the outcome is that creating a custom document class is not the best option as most of the settings are then overridden by package sphinx on line 12 in code above. This package (file sphinx.sty) is copied as well to directory build/latex/.

LaTeX preamble¶

Additional commands may be added as preamble in the generated LaTeX file. This is easily done by editing file conf.py:

f = open('latex-styling.tex', 'r+');
PREAMBLE = f.read();

latex_elements = {
    # The paper size ('letterpaper' or 'a4paper').
    #'papersize': 'a4paper',

    # The font size ('10pt', '11pt' or '12pt').
    #'pointsize': '10pt',

    # Additional stuff for the LaTeX preamble.
    'preamble': PREAMBLE
}

This will copy the contents of file latex-styling.tex (in same directory as conf.py) to the generated LaTeX document. For instance, if latex-styling.tex reads:

% My personal "bold" command
\newcommand{\mycommand}[1]{\textbf{#1}}

the generated LaTeX document becomes:

% Generated by Sphinx.
\def\sphinxdocclass{report}
\documentclass[a4paper,10pt,english]{sphinxmanual}
% snip (packages)
% My personal "bold" command
\newcommand{\mycommand}[1]{\textbf{#1}}

\title{My Extension Documentation}
\date{2013-06-30 22:25}
\release{1.0.0}
\author{Xavier Perseguers}

Other options¶

The configuration file conf.py lets you further tune the rendering with LaTeX. Please consult http://sphinx-doc.org/config.html#options-for-latex-output for further instructions.

TYPO3 template¶

We want to stick as much as possible to default rendering, to avoid having to change the LaTeX code generation from Sphinx. As such, we choose to include a custom package typo3 (file typo3.sty) that will override some settings of package sphinx. To include it automatically, we simply use the preamble option of conf.py:

latex_elements = {
    # Additional stuff for the LaTeX preamble.
    'preamble': '\\usepackage{typo3}'
}

The package typo3 is available from a dedicated repository, within directory latex.typo3/ and is automatically copied to the build directory when using this extension. Alternatively, you may want to register it globally within TEXMF if you plan to generate PDF from the command line solely.