An Intro to rst2pdf - Changing Restructured Text into PDFs with Python

There are several cool ways to create PDFs with Python. In this article we will be focusing on a cool little tool called rst2pdf, which takes a text file that contains Restructured Text and converts it to a PDF. The rst2pdf package requires Reportlab to function. This won’t be a tutorial on Restructured Text, although we’ll have to discuss it to some degree just to understand what’s going on.

Getting Started

First off we’ll need to create a document with the required markup. Let’s do that first. Here’s some simple restructured text with a couple of directives mixed in. We’ll explain everything after you’ve had a chance to read the code:

.. header:: Python Rules! - page ###Page###


=====

Title

=====
This is some blah blah blah
.. raw:: pdf
   PageBreak oneColumn
New section

===========
yada yada yada
.. code-block:: python
	import urllib

	import urllib2

	import webbrowser
	url = "http://duckduckgo.com/html"

	data = urllib.urlencode({'q': 'Python'})

	results = urllib2.urlopen(url, data)

	with open("results.html", "w") as f:

		f.write(results.read())

webbrowser.open("results.html")

The first couple lines define the header that will be on every page. In this case, we’re going to have “Python Rules!” printed at the top of every page along with a page number. There are several other special hash-mark insert directives available. You should check out the official documentation for more information on those. Then we have a Title. Note that it is preceded and followed by a bunch of equal signs that are the same length as the text. This tells us that this text will be styled and centered. The following line is just a lame sentence for demonstration purposes. Next up is another special directive which tells rst2pdf to insert a page break. The second page contains a section header, a lame sentence and a code example that’s color-coded.

To generate the PDF, you’ll need to do something like this on the command line:

rst2pdf test.rst -o out.pdf

You can also run rst2pdf against a config file to control some of the special PDF directives, like header and footer, etc. The information about how to make the config file get read is a little confusing though. It sounds like you have to place the file in a specific location: /etc/rst2pdf.conf and ~/.rst2pdf/config. There’s also a –config flag you can pass, but I’ve found various reports online that that doesn’t work, so your mileage may vary. There’s a sample config file in the project’s repo that you’ll find instructive.

Wrapping Up

I was hoping that rst2pdf would allow an easy way to specify absolute positions and create lines and boxes so I could replace an XSL / XML project I was working on with something much more simple. Alas, rst2pdf just doesn’t support the lines and boxes that reportlab itself does at the time of this writing. However if you need something easy to use to create your documents with and you already know restructured text, I think this is a very good way to go. You can also take your restructured text skills and use them with the Sphinx documentation project.