Friday, May 11, 2012

Create a PDF document from your Sphinx Documentation using rst2pdf

Pre-requisites & Assumptions

  • You have installed Python.
  • You have installed and used Sphinx documentation generator.
  • You have created an HTML documentation using Sphinx

Download & Install rst2pdf

  • Extract the compressed files and install rst2pdf using the command : python setup.py install

Create the PDF File

Now to create a PDF out of the HTML documentation that you have created, do the following
  • Go to your Sphinx documentation folder, open conf.py in a text editor, and edit the following line under General Configuration to include the "rst2pdf.pdfbuilder" extension:
======== 
extensions = ['sphinx.ext.doctest','rst2pdf.pdfbuilder']
========
  • Again in the conf.py file, add the below content at the end. Change the pdf_documents parameter according your project (index filename, pdf file name, document title on first page, and the author name)
===========

# -- Options for PDF output --------------------------------------------------


# Grouping the document tree into PDF files. List of tuples
# (source start file, target name, title, author, options).
#
# If there is more than one author, separate them with \\.
# For example: r'Guido van Rossum\\Fred L. Drake, Jr., editor'
#
# The options element is a dictionary that lets you override
# this config per-document.
# For example,
# ('index', u'MyProject', u'My Project', u'Author Name',
#  dict(pdf_compressed = True))
# would mean that specific document would be compressed
# regardless of the global pdf_compressed setting.


pdf_documents = [
('index', u'EMSDocumentation', u'EMS Documentation', u'Thyag Sundaramoorthy'),
]


# A comma-separated list of custom stylesheets. Example:
pdf_stylesheets = ['sphinx','kerning','a4']


# A list of folders to search for stylesheets. Example:
pdf_style_path = ['.', '_styles']


# Create a compressed PDF
# Use True/False or 1/0
# Example: compressed=True
#pdf_compressed = False


# A colon-separated list of folders to search for fonts. Example:
# pdf_font_path = ['/usr/share/fonts', '/usr/share/texmf-dist/fonts/']


# Language to be used for hyphenation support
#pdf_language = "en_US"


# Mode for literal blocks wider than the frame. Can be
# overflow, shrink or truncate
#pdf_fit_mode = "shrink"


# Section level that forces a break page.
# For example: 1 means top-level sections start in a new page
# 0 means disabled
#pdf_break_level = 0


# When a section starts in a new page, force it to be 'even', 'odd',
# or just use 'any'
#pdf_breakside = 'any'


# Insert footnotes where they are defined instead of
# at the end.
#pdf_inline_footnotes = True


# verbosity level. 0 1 or 2
#pdf_verbosity = 0


# If false, no index is generated.
#pdf_use_index = True


# If false, no modindex is generated.
#pdf_use_modindex = True


# If false, no coverpage is generated.
#pdf_use_coverpage = True


# Name of the cover page template to use
#pdf_cover_template = 'sphinxcover.tmpl'


# Documents to append as an appendix to all manuals.
#pdf_appendices = []


# Enable experimental feature to split table cells. Use it
# if you get "DelayedTable too big" errors
#pdf_splittables = False


# Set the default DPI for images
#pdf_default_dpi = 72


# Enable rst2pdf extension modules (default is only vectorpdf)
# you need vectorpdf if you want to use sphinx's graphviz support
#pdf_extensions = ['vectorpdf']


# Page template name for "regular" pages
#pdf_page_template = 'cutePage'


# Show Table Of Contents at the beginning?
#pdf_use_toc = True


# How many levels deep should the table of contents be?
pdf_toc_depth = 9999


# Add section number to section references
pdf_use_numbered_links = False


# Background images fitting mode
pdf_fit_background_mode = 'scale'
===============

  • Open your documentation's make.bat file, and add the following content :
===== 
if  "%1" == "pdf" (
    %SPHINXBUILD% -b pdf %ALLSPHINXOPTS% %BUILDDIR%/pdf
    echo.
echo.Build finished. The PDF files are in %BUILDDIR%/pdf
    goto end
)
=====

  • Now open cmd prompt, navigate to your documentation directory and hit the command : make pdf
  • The pdf document should have been created in the ./build/pdf directory.

4 comments:

Erich Reiter said...

Thank Thyag for the post.

Do you know how to insert multiple html files so that it outputs 1 single pdf? I didn't see this in the options.

Baptiste Pesquet said...

This was very useful.
Thanks a lot !

Kobi Kalif said...

Thank you for this post, very useful! can you also explain how to use it if i'm using build_sphinx command as part of python setuptools?

Anbuchelvan ponnusamy said...

Thank Thyag for the post.

I try all above your steps. But I got a an error as "Running Sphinx v1.3.1

Extension error:
Could not import extension rst2pdf.pdfbuilder (exception: No module named report
lab.lib.styles)". please help to solve this problem.