Posts about rst2pdf

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.com.ar

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:

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!

Rst2pdf 0.16 is out!

Finally, a new release of rst2pdf!

You can get it at its site: http://rst2pdf.googlecode.com

rst2pdf is a tool to convert restructured text (a light, cool markup language) to PDF using reportlab instead of LaTeX.

It has been used for many things, from books, to magazines, to brochures, to manuals, to websites and has lots of features:

  • Font embedding (TTF or Type1 fonts)
  • Cascading Stylesheets
  • Extremely flexible plugin architecture (you can do things like render the headings from arbitrary SVG files!)
  • Sphinx integration.
  • Configurable page layouts
  • Custom cover pages via templates
  • And much, much more...

The biggest change in 0.16 is surely the improved support for Sphinx 1.0.x so if you are using Sphinx, you really want this version.

Also, it has a ton of bugfixes, and a few minor but useful new features.

Here's the whole changelog if you don't believe me:

  • Fixed Issue 343: Plugged memory leak in the RSON parser.
  • Fix for Issue 287: there is still a corner case if you have two sections with the same title, at the same level, in the same page, in different files where the links will break.
  • Fixed Issue 367: german-localized dates are MM. DD. YYYY so when used in sphinx's template cover they appeared weird, like a list item. Fixed with a minor workaround in the template.
  • Fixed Issue 366: links to "#" make no sense on a PDF file
  • Made definitions from definition lists more stylable.
  • Moved definition lists to SplitTables, so you can have very long definitions.
  • Fixed Issue 318: Implemented Domain specific indexes for Sphinx 1.0.x
  • Fixed Index links when using Sphinx/pdfbuilder.
  • Fixed Issue 360: Set literal.wordWrap to None by default so it doesn't inherit wordWrap CJK when you use the otherwise correct japanese settings. In any case, literal blocks are not supposed to wrap at all.
  • Switched pdfbuilder to use SplitTables by default (it made no sense not to do it)
  • Fixed Issue 365: some TTF fonts don't validate but they work anyway.
  • Set a valid default baseurl for Sphinx (makes it much faster!)
  • New feature: --use-numbered-links to show section numbers in links to sections, like "See section 2.3 Termination"
  • Added stylesheets for landscape paper sizes (i.e: a4-landscape.style)
  • Fixed Issue 364: Some options not respected when passed in per-doc options in sphinx.
  • Fixed Issue 361: multiple linebreaks in line blocks were collapsed.
  • Fixed Issue 363: strange characters in some cases in math directive.
  • Fixed Issue 362: Smarter auto-enclosing of equations in $...$
  • Fixed Issue 358: --real--footnotes defaults to False, but help text indicates default is True
  • Fixed Issue 359: Wrong --fit-background-mode help string
  • Fixed Issue 356: missing cells if a cell spawns rows and columns.
  • Fixed Issue 349: Work correctly with languages that are available in form aa_bb and not aa (example: zh_cn)
  • Fixed Issue 345: give file/line info when there is an error in a raw PDF directive.
  • Fixed Issue 336: JPEG images should work even without PIL (but give a warning because sizes will probably be wrong)
  • Fixed Issue 351: footnote/citation references were generated incorrectly, which caused problems if there was a citation with the same text as a heading.
  • Fixed Issue 353: better handling of graphviz, so that it works without vectorpdf but gives a warning about it.
  • Fixed Issue 354: make todo_node from sphinx customizable.
  • Fixed bug where nested lists broke page layout if the page was small.
  • Smarter --inline-links option
  • New extension: fancytitles, see http://lateral.netmanagers.com.ar/weblog/posts/BB906.html
  • New feature: tab-width option in code-block directive (defaults to 8).
  • Fixed Issue 340: endnotes/footnotes were not styled.
  • Fixed Issue 339: class names using _ were not usable.
  • Fixed Issue 335: ugly crash when using images in some specific places (looks like a reportlab bug)
  • Fixed Issue 329: make the figure alignment/class attributes work more like LaTeX than HTML.
  • Fixed Issue 328: list item styles were being ignored.
  • Fixed Issue 186: new --use-floating-images makes images with :align: set work like in HTML, with the next flowable flowing beside it.
  • Fixed Issue 307: header/footer from stylesheet now supports inline rest markup and substitutions defined in the main document.
  • New pdf_toc_depth option for Sphinx/pdfbuilder
  • New pdf_use_toc option for Sphinx/pdfbuilder
  • Fixed Issue 308: compatibility with reportlab from SVN
  • Fixed Issue 323: errors in the config.sample made it work weird.
  • Fixed Issue 322: Image substitutions didn't work in document title.
  • Implemented Issue 321: underline and strikethrough available in stylesheet.
  • Fixed Issue 317: Ugly error message when file does not exist