Background images and multiple styles in rst2pdf

Over the weekend I released rst2pdf 0.99. The list of changes is quite long as it’s been over a year since the last release.

There are some key things in this release that I’m particularly pleased about including Python 3.9 and 3.10 & Sphinx 4 support, multiple styles in the class directive and the ability to specify background images in the raw:: pdf directive. There’s also a number of bug fixes, particular to math rendering and errors.

I use rst2pdf to write the slides for talks that I give, so going to use background images and multiple styles in `class` a lot!

Background images

It’s not uncommon that I want a background image on a slide for a title page. Prior to 0.99, I would do this in presentation.rst:

.. raw:: pdf

  PageBreak docsTitlePage

.. class:: title

  Docs

with a page template defined in style.yaml:

pageTemplates:
  docsTitlePage:
    background: backgrounds/books.jpg
    frames:
    - [2%, 0%, 96%, 70%]
    showFooter: true
    showHeader: false

For every different background image, I have do define a new page template in my style file isn’t great.

With rst2pdf 0.99, I can specify the image in the PageBreak directive:

.. raw:: pdf

  PageBreak titlePage background=backgrounds/books.jpg

.. class:: title

  Docs

Now, just one page template is required for all my title pages.

Multiple styles in the class directive

Another situation I sometimes have is when I want to apply more than one style modifier to some text.

For example, rendering multiple paragraphs that need to be aligned differently with different colours. Previously, I would generate a new style for each combination:

  centred-highlight:
    alignment: TA_CENTER
    textColor: green

  left-highlight:
    alignment: TA_LEFT
    textColor: green

  right-highlight:
    alignment: TA_RIGHT
    textColor: green

  centred-lowlight:
    alignment: TA_CENTER
    textColor: darkgreen

  left-lowlight:
    alignment: TA_LEFT
    textColor: darkgreen

  right-lowlight:
    alignment: TA_RIGHT
    textColor: darkgreen

and so on, depending on which combinations are needed.

I can then use like this in my rst file:

.. class:: right-highlight

  Text goes here.

.. class:: left-lowlight

  Text goes here.

With rst2pdf 0.99, we can now specify more than one style in the class directive, so we can separate the styles:

  centred:
    alignment: TA_CENTER
  left:
    alignment: TA_LEFT
  right:
    alignment: TA_RIGHT
  highlight:
    textColor: green
  lowlight:
    textColor: darkgreen

and then apply them appropriately:

.. class:: right highlight

  Text goes here.

.. class:: left lowlight

  Text goes here.

Hopefully, this will make my style file that much clearer and easier to understand!

Try it out

With rst2pdf 0.99 we are getting very close now to 1.0 now and I’d love to see some people kick the tyres and see if it works for them. Restructured Text is a good markup format for documentation and is easy to publish to the web and PDF. Try it out and report any issues you find on GitHub.