Developing software in the Real World

Step debugging sphinx-build in PyCharm

I've been trying to solve an issue with the rst2pdf Sphinx extension which allows you to use rst2pdf to create a PDF of your Sphinx documentation rather than using Sphinx's default pdfTeX builder. In order to understand what was happening, I really wanted to inspect variable at certain stages of the process, which is easiest with a step debugger. As I already use PhpStorm for step debugging PHP, I fired up PyCharm and worked out… continue reading.

rst2pdf: back from the dead!

Today marks a momentous day! I've released 0.94 of rst2pdf to PyPI! If you have a need to convert plain text files to PDF, check it out. As the last release, 0.93, was December 2012, I think you could have reasonably assumed that the project was abandoned. So why did I bring it back from the dead?

Automatically converting PDF to Keynote

I use rst2pdf to create presentations which provides me with a PDF file. When it comes to presenting on stage, on Linux there are tools such as pdfpc and on Mac there's Keynote. Keynote doesn't read PDF files by default, so we have to convert them and the tool I use for this is Melissa O'Neill's PDF to Keynote. This is a GUI tool, so I manually create the Keynote file when I need it… continue reading.

Auto reloading a PDF on OS X

Currently, I create presentations using rst2pdf and so I regularly have vim open side by side with the Preview app showing the rendered PDF. I use a Makefile to create the PDF from the rst sources, so I just use :make in vim to rebuild the PDF file and then had to switch to Preview in order for it to reload the updated PDF file. Recently a friend wondered why the PDF viewer couldn't reload… continue reading.

Styling rst2pdf tables

I currently use rst2pdf to create presentations slide decks from reStructured Text files. I like rST a lot as it's more expressive than Markdown and allows for extension. Tables in rST are marked up like this:

We create a PDF file with the command rst2pdf test.rst which produces a table that looks like this: To style, this we create styles within a style file and then compile using rst2pdf test.rst -s my.style. Let's start… continue reading.

Jerry-rigging pygments to support new PHP keywords

I use rst2pdf to create my presentations and noticed that the syntax highlighter wasn't highlighting instanceof. rst2pdf uses pygments for syntax highlighting, so I wondered what was going on. A short investigation led to me realise that the current stable version of pigments is 1.6 and they are working on 2.0. It seems that 2.0 has a number of changes to the PHP lexer, which aren't in 1.6. While I'm waiting, I modified my local… continue reading.

rst2html does not support :startinline:

I'm currently writing some documentation in Restructured Text that I'm targeting at HTML and PDF using rst2html and rst2pdf. For syntax highlighting, both rst2html and rst2pdf use Pygments, however rst2html doesn't support any Pygments options. So a typical PHP snippet in rst targeting rst2pdf, would be written as:

The startinline Pygments option is to allow it to highlight the snippet, even though the opening <?php is missing. If you run rst2html, you get this… continue reading.

Notes on embedding fonts in rst2pdf

I wanted to use Helvetica Light in a PDF that I'm creating using rst2pdf and this proved a little tricker than I expected. Note that to use fonts with rst2pdf, you need to install fontconfig using brew:

Now, on to the problem! In this case, I discovered that setting stdFont: Helvetica-Light or stdFont: HelveticaLight in the style file resulted in Verdana being used in the PDF file! Fortunately, the -v switch to rst2pdf is… continue reading.