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!
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.