Sphinx PDF themes

There are no predefined themes for PDF output for Sphinx. But LaTex offers a rich set of options to style the document. My problem was to find the proper way to style the document with sphinx. Here the way, which worked for me:

First take a look into the conf.py. There you'll find an option latex_elements. With this option you can add your own LaTex commands to the output. For example:

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

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

'fontpkg': r"""
\PassOptionsToPackage{bookmarksnumbered}{hyperref}

""",

# Additional stuff for the LaTeX preamble.
'preamble': r"""
\usepackage{setspace}
""",

'footer': r"""
""",

'maketitle': r'''
\pagenumbering{arabic}
''',
}

There are a few points important to know.

  • Use r""" to avoid conflicts with python
  • Though preamble would be the right point to add \usepackage you can have conflicts with the Sphinx default settings. Look at fontpkg in the example. It is the first include in the .tex output document. If you have to set options for default packages, do it here.
  • maketitle let you define your own title page. See some latex documentation. I set \pagenumbering there to have the table of contents with arabic numbers, so the real content begins on page "1".

With the right knowledge of Latex commands you can get good theming with a few commands. A good source to find help is https://tex.stackexchange.com/ where most common problems have a solution. But finding the proper Latex commands is much more difficult than to choose a theme as done for HTML.

It might be helpful to take a look in the Tex-Output under ./_build. There you can see, how the latex_elements-options were included in the document.


Firstly, Sphinx doesn't generate PDF output by itself, though there are three general methods to get from Sphinx source files to PDF output:

  1. Use the Latex builder, and then a separate tool like latex2pdf to generate the PDF output
  2. Use the Sphinx plugin from the rst2pdf project
  3. Use the rinoh Sphinx builder provided by rinohtype

That being said there is lots of potential for customizing the styling of your PDF output using either method.

  1. When using the latex->pdf method, you can customize your latex output using a number of options in your sphinx config file. See here. This method is somewhat less convenient than the HTML themes that Sphinx uses for HTML generation, though (IMO).
  2. When using rst2pdf you can define your own stylesheet, which is described in more detail in the manual (look under the "Styles" heading). rst2pdf includes a number of stylesheets, which can be combined for various results. And of course, you can also modify them or create your own (they're just JSON files). These stylesheets also support a kind of inheritance, so act more like the Sphinx HTML themes than the previous method.
  3. rinohtype has extensive provisions for styling a document. See the Basic Document Styling and subsequent sections of the rinohtype manual.

Tags:

Pdf

Python Sphinx

Themes

Recent Posts