Hiding Sections With Rst2pdf

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:

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.

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

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

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:

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

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!

Leave a Reply

Please use [code] and [/code] around any source code you wish to share.

This site uses Akismet to reduce spam. Learn how your comment data is processed.

To respond on your own website, enter the URL of your response which should contain a link to this post's permalink URL. Your response will then appear (possibly after moderation) on this page. Want to update or remove your response? Update or delete your post and re-enter your post's URL again. (Find out more about Webmentions.)