Ir al contenido principal

Ralsina.Me — El sitio web de Roberto Alsina

Publicaciones sobre 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 Di­nu Gher­man: you can use rs­t2­pdf as a flo­wa­ble ge­ne­ra­tor for re­por­tlab. Su­ppo­se you want to crea­te, in a re­por­tlab "s­to­r­y", a bun­ch of pa­ra­gra­phs, wi­th em­pha­sis, li­nks, etc, and perhaps a ta­ble.

Using res­truc­tu­red tex­t, it's so­me­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 cour­se, per­fec­tly po­s­si­ble to ge­ne­ra­te a bun­ch of re­por­tlab (or ra­ther pla­ty­pus) flo­wa­bles to re­pre­sent all this. It wi­ll just mean so­me 75 li­nes of co­de. And if you chan­ge an­y­thin­g, then you ha­ve to edit co­de!

Or you can take ad­van­ta­ge of rs­t2­pdf 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­du­ces this pdf. And of cour­se edi­ting it is ra­ther ea­sier than edi­ting co­de. Sin­ce you are not using rs­t2­pdf to do the fi­nal PDF ge­ne­ra­tio­n, you can use the­se flo­wa­bles in your own do­cu­men­ts.

The bad news

So­me things wi­ll not wo­rk, like hea­dings, sin­ce rs­t2­pdf crea­tes flo­wa­bles that do a ton of things like adding the­msel­ves on in­dexes and su­ch. If you want a hea­din­g-­like thing you can use cla­sses:

.. class:: heading1

This will look like a heading

This is a regular paragraph.

Other ran­dom res­truc­tu­red text fea­tu­res may or may not wo­rk, like footno­tes or ci­ta­tion­s.

Rst2pdf 0.93 released

A bit ahead of sche­du­le, I just uploaded ver­sion 0.93 of rs­t2­pdf a tool to con­vert res­truc­tu­red text in­to PDF fi­le­s.

He­re are so­me of the chan­ges in this ver­sio­n:

  • Fixed Is­­sue 447: Dou­­ble-­­si­­ded alwa­­ys sta­r­­ts on the ri­­ght (By Rob Lu­­dwi­­ck)

    • Re­­­mo­­­­­ved --­­­fi­r­s­­­t-­­­pa­­­ge-e­­­ven as it was not us­ed an­­­ywhe­­­re.

    • Added --­­­fi­r­s­­­t-­­­pa­­­ge-o­­­n-­­­ri­­­ght

  • Fixed Is­­sue 464: su­­pport ali­g­n­­ment via :cla­ss: in ima­­ge di­­re­c­­ti­­ve­s.

  • Fixed Is­­sue 482: Li­­ne blo­­­cks wi­­th in­­den­ted pa­r­­ts get ex­­tra­­neous spa­­cing

  • Fixed Is­­sue 470: Su­­pport for :ta­r­­ge­­t: in fi­­gu­­res.

  • New sty­­le "i­­ma­­ge" to be applied to ima­­ge di­­re­c­­ti­­ve­s.

  • Fixed Is­­sue 485: Be­­­tter sty­­ling su­­pport for fi­­gu­­res/i­­ma­­ges (s­­pa­­ce­­Be­­­fo­­­re/A­­fte­­r)

  • Su­­pport rs­­t2­­pdf [inf [ou­­tf]] syn­­tax to be mo­­­re co­m­­pa­­ti­­ble wi­­th rs­­t2*

  • Im­­ple­­men­ted Is­­sue 389: New --s­­tri­­p-e­­le­­men­­t-wi­­th-­­cla­ss op­­tion

  • Fixed Is­­sue 474: Ce­­ll­S­­ty­­le1 is not the­­re in re­­po­r­­tlab 2.6

  • Re­­mo­­­ved de­­fault pa­­dding from De­­la­­ye­­dTa­­ble, whi­­ch looked bad on hea­­de­r­s/­­foote­r­s.

  • Im­­pro­­­ve­­men­­ts to the ma­­th di­­re­c­­ti­­ve (font co­­­lor and si­­ze)

  • Be­­­tter su­­pport for sty­­ling li­­te­­ra­l­s.

  • Fixed Is­­sue 454 (S­­pli­­tting fai­­lu­­re)

  • Re­­gress­ed Is­­sue 374 (so­­­me li­­te­­ral blo­­­cks get overspli­­t)

  • Swi­­tched from sv­­glib to sv­­g2rlg

  • Re­­mo­­­ved uni­­co­n­­ve­r­­tor su­­pport

  • Fixed Is­­sue 477: Si­nk footno­­­te se­­pa­­ra­­tor (pa­­tch by ase­r­­ma­­x)

  • Fixed Is­­sue 473: Su­­pport "co­­­de" di­­re­c­­ti­­ve like an alias of co­­­de-­­blo­­­ck.

  • Fixed Is­­sue 472: Im­­ple­­men­ted MyI­­ma­­ge._un­­Res­­tri­c­­tSi­­ze

  • Fixed Is­­sue 471: Res­­pect cla­ss in li­­ne­­blo­­­cks.

  • Fixed Is­­sue 455: New pi­s­a/­­xh­t­­m­­l2­­pdf has ve­­ry di­­ffe­­rent im­­po­r­­ts

  • Ma­­rked Is­­sue 358 as fixe­­d.

  • Fixed Is­­sue 410: alwa­­ys in­­clu­­de fu­­ll li­­nes in co­­­de-­­blo­­­cks (m­­mue­­ller pa­­tch)

Rst2pdf progress

I ha­ve set for myself a prio­ri­ty list of bugs that bo­ther me in rs­t2­pdf, my tool to con­vert res­truc­tu­red text in­to PDFs in or­der of de­crea­sing sha­me­ful­ness.

I ha­ve been fi­xing a few to­day (ear­ly mor­ning + la­te ni­ght ha­ck) so the fo­llo­wing is now co­rrec­t:

  • Use of in­­clu­­ded sty­­le­s­hee­­ts

  • Ve­r­­ti­­cal spa­­cing of in­­den­ted li­­ne­­blo­­­cks

  • Use of :ta­r­­ge­­t: in fi­­gu­­re di­­re­c­­ti­­ves

The­re are 46 open is­sues but I am not plan­ning on fi­xing them all. My per­so­nal hi­tlist has 10 mo­re bugs in it, but re­gard­le­ss of how many I fix, I in­tend to re­lea­se an­ywa­y, be­cau­se:

  • Last re­­lea­­se is bro­­ken wi­­th la­­test re­­po­r­­tlab

  • Last re­­lea­­se is a bit bro­­ken wi­­th do­­­cu­­tils 0.10 whi­­ch wi­­ll be out soon

  • Last re­­lea­­se was over six mo­n­­ths ago

And that last one is the cri­ti­cal one. Wo­rking at Ca­no­ni­cal has sho­wn me that re­lea­se ca­den­ce is good. Spe­cia­lly in a pro­ject whe­re trunk is ve­ry ra­re­ly bro­ken (like rs­t2­pdf) the­re is no rea­son for slow re­lea­se cy­cle­s. Rs­t2­pdf should re­lea­se mon­th­l­y.

I fu­lly in­tend to take that appro­ach, so the next re­lea­se wi­ll be do­ne on De­cem­ber 21s­t.

Rst2PDF Release Plans

I ha­ve spent a li­ttle ti­me on rs­t2­pdf the­se last few da­ys. It does­n't look too ba­d, con­si­de­ring the long ne­glec­t, but the­re is so­me breaka­ge.

After going over al­most 300 in­te­gra­tion tes­ts by han­d, I iden­ti­fied a few re­gres­sions (and a cou­ple of bugs that fixed the­msel­ve­s, ya­y).

So, in or­der to do a re­lea­se, I am ho­ping to fix the­s­e:

I pro­ba­bly wi­ll not fix them all, and trunk wo­rks mu­ch be­tter for many ca­ses than 0.92 so I should not blo­ck a re­lea­se on any of the­s­e, rea­ll­y. I wi­ll gi­ve myself a cou­ple of weeks to see how many (if an­y) I can get do­ne.

On the other han­d, if an­yo­ne rea­ding this feels ad­ven­tu­rous, and wan­ts to lend a han­d, help is alwa­ys wel­co­me.

In the meanti­me, this is a list of wha­t's chan­ged in trunk from ver­sion 0.92:

  • Su­­pport rs­­t2­­pdf [inf [ou­­tf]] syn­­tax to be mo­­­re co­m­­pa­­ti­­ble wi­­th rs­­t2*

  • Im­­ple­­men­ted Is­­sue 389: New --s­­tri­­p-e­­le­­men­­t-wi­­th-­­cla­ss op­­tion

  • Fixed Is­­sue 474: Ce­­ll­S­­ty­­le1 is not the­­re in re­­po­r­­tlab 2.6

  • Re­­mo­­­ved de­­fault pa­­dding from De­­la­­ye­­dTa­­ble, whi­­ch looked bad on hea­­de­r­s/­­foote­r­s.

  • Im­­pro­­­ve­­men­­ts to the ma­­th di­­re­c­­ti­­ve (font co­­­lor and si­­ze)

  • Be­­­tter su­­pport for sty­­ling li­­te­­ra­l­s.

  • Fixed Is­­sue 454 (S­­pli­­tting fai­­lu­­re)

  • Swi­­tched from sv­­glib to sv­­g2rlg

  • Re­­mo­­­ved uni­­co­n­­ve­r­­tor su­­pport

  • Fixed Is­­sue 477: Si­nk footno­­­te se­­pa­­ra­­tor (pa­­tch by ase­r­­ma­­x)

  • Fixed Is­­sue 473: Su­­pport "co­­­de" di­­re­c­­ti­­ve like an alias of co­­­de-­­blo­­­ck.

  • Fixed Is­­sue 472: Im­­ple­­men­ted MyI­­ma­­ge._un­­Res­­tri­c­­tSi­­ze

  • Fixed Is­­sue 471: Res­­pect cla­ss in li­­ne­­blo­­­cks.

  • Fixed Is­­sue 455: New pi­s­a/­­xh­t­­m­­l2­­pdf has ve­­ry di­­ffe­­rent im­­po­r­­ts

  • Ma­­rked Is­­sue 358 as fixed (Li­­te­­ral blo­­­cks ren­­de­­red wi­­th la­r­­ge bo­­­ttom ma­r­­gi­n)

  • Fixed Is­­sue 410: alwa­­ys in­­clu­­de fu­­ll li­­nes in co­­­de-­­blo­­­cks (m­­mue­­ller pa­­tch)


Contents © 2000-2024 Roberto Alsina