Posts about rst2pdf

Lois Lane, Reporting

So, 9 years ago I wrote a post about how I would love a tool that took a JSON data file, a Mako template, and generated a report using reStructured Text.

If you don't like that, pretend it says YAML, Jinja2 and Markdown. Anyway, same idea. Reports are not some crazy difficult thing, unless you have very demanding layout or need to add a ton of logic.

And hey, if you do need to add a ton of logic, you do know python, so how hard can it be to add the missing bits?

Well, not very hard. So here it is, 9 years later because I am sitting at an auditorium and the guy giving the talk is having computer problems.

Lois Lane Reports from PyPI. and GitHub

Using rst2pdf in Different Ways

This was an idea by Dinu Gherman: you can use rst2pdf as a flowable generator for reportlab. Suppose you want to create, in a reportlab "story", a bunch of paragraphs, with emphasis, links, etc, and perhaps a table.

Using restructured text, it's something like this:

This is a paragraph. It has a link: http://rst2pdf.ralsina.me and then some random text.

+-------------+---------------------------+
| A table     | With cells                |
|             |                           |
|             |                           |
|             |                           |
|             |                           |
+-------------+---------------------------+
| And inside                              |
| it some                                 |
| more text                               |
|                                         |
|                                         |
+-----------------------------------------+

* And a list
* Just to make it harder

  + with a nested item here

It is, of course, perfectly possible to generate a bunch of reportlab (or rather platypus) flowables to represent all this. It will just mean some 75 lines of code. And if you change anything, then you have to edit code!

Or you can take advantage of rst2pdf and do this:

from docutils.core import publish_doctree
from rst2pdf.createpdf import RstToPdf
from reportlab.lib.units import cm
from reportlab.pdfgen.canvas import Canvas
from reportlab.platypus import Frame

rest_text = """
This is a paragraph. It has a link: http://rst2pdf.ralsina.me and then some random text.

+-------------+---------------------------+
| A table     | With cells                |
|             |                           |
|             |                           |
|             |                           |
|             |                           |
+-------------+---------------------------+
| And inside                              |
| it some                                 |
| more text                               |
|                                         |
|                                         |
+-----------------------------------------+

* And a list
* Just to make it harder

    + with a nested item here
"""
r2p = RstToPdf()
doctree = publish_doctree(rest_text)
story = r2p.gen_elements(doctree)
canv = Canvas("platypus-rest.pdf")
f = Frame(2 * cm, 2 * cm, 16 * cm, 18 * cm, showBoundary=True)
f.addFromList(story, canv)
canv.save()

This produces this pdf. And of course editing it is rather easier than editing code. Since you are not using rst2pdf to do the final PDF generation, you can use these flowables in your own documents.

The bad news

Some things will not work, like headings, since rst2pdf creates flowables that do a ton of things like adding themselves on indexes and such. If you want a heading-like thing you can use classes:

.. class:: heading1

This will look like a heading

This is a regular paragraph.

Other random restructured text features may or may not work, like footnotes or citations.

Rst2pdf 0.93 released

A bit ahead of schedule, I just uploaded version 0.93 of rst2pdf a tool to convert restructured text into PDF files.

Here are some of the changes in this version:

  • Fixed Issue 447: Double-sided always starts on the right (By Rob Ludwick)
    • Removed --first-page-even as it was not used anywhere.
    • Added --first-page-on-right
  • Fixed Issue 464: support alignment via :class: in image directives.
  • Fixed Issue 482: Line blocks with indented parts get extraneous spacing
  • Fixed Issue 470: Support for :target: in figures.
  • New style "image" to be applied to image directives.
  • Fixed Issue 485: Better styling support for figures/images (spaceBefore/After)
  • Support rst2pdf [inf [outf]] syntax to be more compatible with rst2*
  • Implemented Issue 389: New --strip-element-with-class option
  • Fixed Issue 474: CellStyle1 is not there in reportlab 2.6
  • Removed default padding from DelayedTable, which looked bad on headers/footers.
  • Improvements to the math directive (font color and size)
  • Better support for styling literals.
  • Fixed Issue 454 (Splitting failure)
  • Regressed Issue 374 (some literal blocks get oversplit)
  • Switched from svglib to svg2rlg
  • Removed uniconvertor support
  • Fixed Issue 477: Sink footnote separator (patch by asermax)
  • Fixed Issue 473: Support "code" directive like an alias of code-block.
  • Fixed Issue 472: Implemented MyImage._unRestrictSize
  • Fixed Issue 471: Respect class in lineblocks.
  • Fixed Issue 455: New pisa/xhtml2pdf has very different imports
  • Marked Issue 358 as fixed.
  • Fixed Issue 410: always include full lines in code-blocks (mmueller patch)

Rst2pdf progress

I have set for myself a priority list of bugs that bother me in rst2pdf, my tool to convert restructured text into PDFs in order of decreasing shamefulness.

I have been fixing a few today (early morning + late night hack) so the following is now correct:

  • Use of included stylesheets
  • Vertical spacing of indented lineblocks
  • Use of :target: in figure directives

There are 46 open issues but I am not planning on fixing them all. My personal hitlist has 10 more bugs in it, but regardless of how many I fix, I intend to release anyway, because:

  • Last release is broken with latest reportlab
  • Last release is a bit broken with docutils 0.10 which will be out soon
  • Last release was over six months ago

And that last one is the critical one. Working at Canonical has shown me that release cadence is good. Specially in a project where trunk is very rarely broken (like rst2pdf) there is no reason for slow release cycles. Rst2pdf should release monthly.

I fully intend to take that approach, so the next release will be done on December 21st.

Rst2PDF Release Plans

I have spent a little time on rst2pdf these last few days. It doesn't look too bad, considering the long neglect, but there is some breakage.

After going over almost 300 integration tests by hand, I identified a few regressions (and a couple of bugs that fixed themselves, yay).

So, in order to do a release, I am hoping to fix these:

I probably will not fix them all, and trunk works much better for many cases than 0.92 so I should not block a release on any of these, really. I will give myself a couple of weeks to see how many (if any) I can get done.

On the other hand, if anyone reading this feels adventurous, and wants to lend a hand, help is always welcome.

In the meantime, this is a list of what's changed in trunk from version 0.92:

  • Support rst2pdf [inf [outf]] syntax to be more compatible with rst2*
  • Implemented Issue 389: New --strip-element-with-class option
  • Fixed Issue 474: CellStyle1 is not there in reportlab 2.6
  • Removed default padding from DelayedTable, which looked bad on headers/footers.
  • Improvements to the math directive (font color and size)
  • Better support for styling literals.
  • Fixed Issue 454 (Splitting failure)
  • Switched from svglib to svg2rlg
  • Removed uniconvertor support
  • Fixed Issue 477: Sink footnote separator (patch by asermax)
  • Fixed Issue 473: Support "code" directive like an alias of code-block.
  • Fixed Issue 472: Implemented MyImage._unRestrictSize
  • Fixed Issue 471: Respect class in lineblocks.
  • Fixed Issue 455: New pisa/xhtml2pdf has very different imports
  • Marked Issue 358 as fixed (Literal blocks rendered with large bottom margin)
  • Fixed Issue 410: always include full lines in code-blocks (mmueller patch)

New rst2pdf feature: --strip-elements-with-class

First new feature in rst2pdf in a long long time, but it was easy to do, and there was an actual user needing it.

This exposes functionality rst2html already had, so that's probably why it was easy to do ;-)

In any case, what is it and what is it good for?

If you mark something with a class, you can now omit it from the output:

.. class:: ignored

This will not be in the output if you use --strip-elements-with-class=ignored

And it's useful, for example, so you can keep slides and presentation notes in the same file. You just put your notes in a class you strip when producing the slides.

Since some classes are automatically assigned for admonitions, this is extra simple:

.. note:: This is a note admonition.

   Note admonitions always have the note class. So you can strip them easily.

And if you don't strip them, they will look pretty.

Rst2pdf 0.92 released, now has a website.

Just released rst2pdf version 0.92. Rst2pdf is a tool to convert restructured text to PDF without requiring multi-hundred-megabytes of software. It supports styling, multiple page layouts, font embedding, vector images, and much more.

Also, now it has a real website: http://rst2pdf.ralsina.me

Try it out and let me know of the obvious, horrible bug I forgot to fix (happens in most rst2pdf releases ;-)

rst2pdf 0.90 is out

Yes, after many moons, it's out. Here is the (as usual) incomplete changelog:

  • Added raw HTML support, by Dimitri Christodoulou
  • Fixed Issue 422: Having no .afm files made font lookup slow.
  • Fixed Issue 411: Sometimes the windows registry has the font's abspath.
  • Fixed Issue 430: Using --config option caused other options to be ignored (by charles at cstanhope dot com)
  • Fixed Issue 436: Add pdf_style_path to sphinx (by [email protected])
  • Fixed Issue 428: page numbers logged as errors
  • Added support for many pygments options in code-block (by Joaquin Sorianello)
  • Implemented Issue 404: plantuml support
  • Issue 399: support sphinx's template path option
  • Fixed Issue 406: calls to the wrong logging function
  • Implemented Issue 391: New --section-header-depth option.
  • Fixed Issue 390: the --config option was ignored.
  • Added support for many pygments options in code-block (by Joaquin Sorianello)
  • Fixed Issue 379: Wrong style applied to paragraphs in definitions.
  • Fixed Issue 378: Multiline :address: were shown collapsed.
  • Implemented Issue 11: FrameBreak (and conditional FrameBreak)
  • The description of frames in page templates was just wrong.
  • Fixed Issue 374: in some cases, literal blocks were split inside a page, or the pagebreak came too early.
  • Fixed Issue 370: warning about sphinx.addnodes.highlightlang not being handled removed.
  • Fixed Issue 369: crash in hyphenator when specifying "en" as a language.
  • Compatibility fix to Sphinx 0.6.x (For python 2.7 docs)

This release did not focus on Sphinx bugs, so those are probably still there. Hopefully the next round is attacking those.

Abandonment issues: rst2pdf

Of all the corpses of my projects, there is one thatI feel worse about, which is rst2pdf. I feel bad about abandnoning several, but rst2pdf was actually a useful tool, used by a bunch of people, and that it has never gathered enough momentum with other developers is sad.

So, I will pick it up. I will spend about 4 hours a week on it. The plan is to:

  1. Gather some patches that are lingering on the issue tracker
  2. Fix some simple-ish bugs
  3. Make another release with 1) and 2)

And of course:

  1. Not let it fall in disrepair again

In the meantime, here is a nice thing I just heard about. Dimitri Christodoulou has hacked rst2pdf so that it can handle the raw:: html directive.

This, dear friends is completely nuts, absolutely out of scope for any given docutils tool, and just too cool :-)

I will try to hijack his code (proper credit and so on), and incorporate it into rst2pdf.

And Dimitri, or anyone else who wants to do cool stuff with rst2pdf: let me know! I will give you commit rights immediately!