I’ve been using rst2pdf for slides for a year or so, but recently I’ve been converted to using it for everything from documents to emailed reports to handouts. Along the way there were a couple of cases where I wanted to create two similar documents, but one needed to omit some details. A great example is my ZCE questions pack, which when updated to PHP 5.5 I converted to restructuredText. By showing/hiding different sections of the document when I generate the PDF, I can maintain the questions and their answers side-by-side, then create the documents containing questions and answers separately. You could do the same with adding a notes field to slides that are hidden when presenting, but available for handouts.

Omitting Sections

This is a relatively new feature in rst2pdf (added late 2012, according to the blog post), and wasn’t present in the version I had from Ubuntu’s default repositories in Saucy Salamander (version 0.16). I grabbed the latest (version 0.93) though, and this feature works delightfully well.

Here’s a snippet of an rst file:

[pyg language=”rst”]

array_filter
————

.. class:: description

Filters elements of an array using a callback function

.. class:: prototype

array array_filter(array $array , [callable $callback ] )

.. class:: params

**array** – The array to iterate over

.. class:: params

**callback** – The callback function to use

.. class:: return

Returns: Returns the filtered array.

[/pyg]

To generate this document with all the elements present, I use something like this:

[pyg language=”bash”]

rst2pdf -s lj.style ref.rst -o ref.pdf

[/pyg]

The section of the document containing the list of parameters can get a bit long-winded, so I can easily leave out those sections using a command that looks like this:

[pyg language=”bash”]

rst2pdf -s lj.style ref.rst -o –strip-elements-with-class=params quickref.pdf

[/pyg]

This generates the same document using the same styles, but omits the sections I named. You can pass more of the same switch to omit as many classes as you need to for your purposes. I’m now using this in all kinds of places, so I thought I’d share!