Table of contents sidebar in Sphinx LaTeX PDF

Question

I am generating a LaTeX document from Sphinx, and converting it to PDF using pdflatex (from MikTeX). The document is missing a table of contents in the sidebar of the PDF viewer.

If I add manually \usepackage{hyperref} to the tex file, it works. But how can I tell Sphinx to do it in the conf.py project file? There is no (evident) related option in the latex output options.

Thanks!

Answer 1

Section 2.5.3 Customizing the rendering of the Sphinx document mentions:

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://www.sphinx-doc.org/en/stable/config.html#options-for-latex-output for further instructions.

A more direct way of adding content rather than inserting it in a separate file (say, latex-styling.tex), is to specify if verbatim. The next subsection in the documentation mentions this for a specific package typo3:

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

It's better to contain your styling options in a separate latex-styling.tex file that you can include using the preamble key via an f.read(). That way you don't have to update conf.py. Compartmentalization is usually better.