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.