Skip to main content

Ralsina.Me — Roberto Alsina's website

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 da­ta file, a Mako tem­plate, and gen­er­at­ed a re­port us­ing re­Struc­tured Tex­t.

If you don't like that, pre­tend it says YAM­L, Jin­ja2 and Mark­down. Any­way, same idea. Re­ports are not some crazy dif­fi­cult thing, un­less you have very de­mand­ing lay­out or need to add a ton of log­ic.

And hey, if you do need to add a ton of log­ic, you do know python, so how hard can it be to add the miss­ing bit­s?

Well, not very hard. So here it is, 9 years lat­er be­cause I am sit­ting at an au­di­to­ri­um and the guy giv­ing the talk is hav­ing com­put­er prob­lem­s.

Lois Lane Re­ports from PyP­I. and GitHub

Using rst2pdf in Different Ways

This was an idea by Dinu Gher­man: you can use rst2pdf as a flow­able gen­er­a­tor for re­port­lab. Sup­pose you want to cre­ate, in a re­port­lab "s­to­ry", a bunch of para­graph­s, with em­pha­sis, links, etc, and per­haps a ta­ble.

Us­ing re­struc­tured tex­t, it's some­thing 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, per­fect­ly pos­si­ble to gen­er­ate a bunch of re­port­lab (or rather platy­pus) flow­ables to rep­re­sent all this. It will just mean some 75 lines of code. And if you change any­thing, then you have to ed­it code!

Or you can take ad­van­tage 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 pro­duces this pdf. And of course edit­ing it is rather eas­i­er than edit­ing code. Since you are not us­ing rst2pdf to do the fi­nal PDF gen­er­a­tion, you can use these flow­ables in your own doc­u­ments.

The bad news

Some things will not work, like head­ings, since rst2pdf cre­ates flow­ables that do a ton of things like adding them­selves on in­dex­es and such. If you want a head­ing-­like thing you can use class­es:

.. class:: heading1

This will look like a heading

This is a regular paragraph.

Oth­er ran­dom re­struc­tured text fea­tures may or may not work, like foot­notes or ci­ta­tion­s.

Rst2pdf 0.93 released

A bit ahead of sched­ule, I just up­load­ed ver­sion 0.93 of rst2pdf a tool to con­vert re­struc­tured text in­to PDF files.

Here are some of the changes in this ver­sion:

  • Fixed Is­­sue 447: Dou­ble-sid­ed al­ways starts on the right (By Rob Lud­wick)

    • Re­­­moved --­­­first-­­­page-even as it was not used any­where.

    • Added --­­­first-­­­page-on-right

  • Fixed Is­­sue 464: sup­­port align­­ment via :class: in im­age di­rec­­tives.

  • Fixed Is­­sue 482: Line blocks with in­­­den­t­ed parts get ex­­tra­ne­ous spac­ing

  • Fixed Is­­sue 470: Sup­­port for :tar­get: in fig­ures.

  • New style "im­age" to be ap­­plied to im­age di­rec­­tives.

  • Fixed Is­­sue 485: Bet­ter styling sup­­port for fig­ures/im­ages (s­­pace­Be­­fore/After)

  • Sup­­port rst2pdf [inf [out­f]] syn­­tax to be more com­­pat­i­ble with rst2*

  • Im­­ple­­men­t­ed Is­­sue 389: New --strip-ele­­men­t-with­­-­­class op­­tion

  • Fixed Is­­sue 474: Cel­l­Style1 is not there in re­­port­lab 2.6

  • Re­­moved de­­fault pad­d­ing from De­layedTable, which looked bad on head­­er­s/­­foot­er­s.

  • Im­prove­­ments to the math di­rec­­tive (font col­or and size)

  • Bet­ter sup­­port for styling lit­er­al­s.

  • Fixed Is­­sue 454 (S­­plit­t­ing fail­ure)

  • Re­­gressed Is­­sue 374 (some lit­er­al blocks get over­s­plit)

  • Switched from svglib to svg2rlg

  • Re­­moved uni­­con­ver­­tor sup­­port

  • Fixed Is­­sue 477: Sink foot­note sep­a­ra­­tor (patch by aser­­max)

  • Fixed Is­­sue 473: Sup­­port "code" di­rec­­tive like an alias of code-block.

  • Fixed Is­­sue 472: Im­­ple­­men­t­ed My­Im­age._un­Re­stric­t­­Size

  • Fixed Is­­sue 471: Re­spect class in lineblock­­s.

  • Fixed Is­­sue 455: New pisa/x­ht­m­l2pdf has very dif­fer­­ent im­­ports

  • Marked Is­­sue 358 as fixed.

  • Fixed Is­­sue 410: al­ways in­­­clude full lines in code-blocks (m­­mueller patch)

Rst2pdf progress

I have set for my­self a pri­or­i­ty list of bugs that both­er me in rst2pdf, my tool to con­vert re­struc­tured text in­to PDFs in or­der of de­creas­ing shame­ful­ness.

I have been fix­ing a few to­day (ear­ly morn­ing + late night hack) so the fol­low­ing is now cor­rec­t:

  • Use of in­­­clud­ed stylesheets

  • Ver­ti­­cal spac­ing of in­­­den­t­ed lineblocks

  • Use of :tar­get: in fig­ure di­rec­­tives

There are 46 open is­sues but I am not plan­ning on fix­ing them al­l. My per­son­al hitlist has 10 more bugs in it, but re­gard­less of how many I fix, I in­tend to re­lease any­way, be­cause:

  • Last re­lease is bro­ken with lat­est re­­port­lab

  • Last re­lease is a bit bro­ken with do­cu­tils 0.10 which will be out soon

  • Last re­lease was over six months ago

And that last one is the crit­i­cal one. Work­ing at Canon­i­cal has shown me that re­lease ca­dence is good. Spe­cial­ly in a project where trunk is very rarely bro­ken (like rst2pdf) there is no rea­son for slow re­lease cy­cles. Rst2pdf should re­lease month­ly.

I ful­ly in­tend to take that ap­proach, so the next re­lease will be done on De­cem­ber 21st.

Rst2PDF Release Plans

I have spent a lit­tle time on rst2pdf these last few days. It does­n't look too bad, con­sid­er­ing the long ne­glec­t, but there is some break­age.

Af­ter go­ing over al­most 300 in­te­gra­tion tests by hand, I iden­ti­fied a few re­gres­sions (and a cou­ple of bugs that fixed them­selves, yay).

So, in or­der to do a re­lease, I am hop­ing to fix the­se:

I prob­a­bly will not fix them al­l, and trunk works much bet­ter for many cas­es than 0.92 so I should not block a re­lease on any of the­se, re­al­ly. I will give my­self a cou­ple of weeks to see how many (if any) I can get done.

On the oth­er hand, if any­one read­ing this feels ad­ven­tur­ous, and wants to lend a hand, help is al­ways wel­come.

In the mean­time, this is a list of what's changed in trunk from ver­sion 0.92:

  • Sup­­port rst2pdf [inf [out­f]] syn­­tax to be more com­­pat­i­ble with rst2*

  • Im­­ple­­men­t­ed Is­­sue 389: New --strip-ele­­men­t-with­­-­­class op­­tion

  • Fixed Is­­sue 474: Cel­l­Style1 is not there in re­­port­lab 2.6

  • Re­­moved de­­fault pad­d­ing from De­layedTable, which looked bad on head­­er­s/­­foot­er­s.

  • Im­prove­­ments to the math di­rec­­tive (font col­or and size)

  • Bet­ter sup­­port for styling lit­er­al­s.

  • Fixed Is­­sue 454 (S­­plit­t­ing fail­ure)

  • Switched from svglib to svg2rlg

  • Re­­moved uni­­con­ver­­tor sup­­port

  • Fixed Is­­sue 477: Sink foot­note sep­a­ra­­tor (patch by aser­­max)

  • Fixed Is­­sue 473: Sup­­port "code" di­rec­­tive like an alias of code-block.

  • Fixed Is­­sue 472: Im­­ple­­men­t­ed My­Im­age._un­Re­stric­t­­Size

  • Fixed Is­­sue 471: Re­spect class in lineblock­­s.

  • Fixed Is­­sue 455: New pisa/x­ht­m­l2pdf has very dif­fer­­ent im­­ports

  • Marked Is­­sue 358 as fixed (L­it­er­al blocks ren­dered with large bot­­tom margin)

  • Fixed Is­­sue 410: al­ways in­­­clude full lines in code-blocks (m­­mueller patch)