Styling rst2pdf tables

I currently use rst2pdf to create presentations slide decks from reStructured Text files. I like rST a lot as it’s more expressive than Markdown and allows for extension.

Tables in rST are marked up like this:

+-----------+-----------+-----------+
| Heading 1 | Heading 2 | Heading 3 |
+===========+===========+===========+
| a         | b         | c         |
|           |           |           |
| aa        |           |           |
+-----------+-----------+-----------+
| d         | e         | f         |
+-----------+-----------+-----------+
| g         | h         | i         |
+-----------+-----------+-----------+
| j         | k         | l         |
+-----------+-----------+-----------+

We create a PDF file with the command rst2pdf test.rst which produces a table that looks like this:

To style, this we create styles within a style file and then compile using rst2pdf test.rst -s my.style.

Let’s start with the table element:

styles:
    table:
      commands: []
         [VALIGN, [ 0, 0 ], [ -1, -1 ], TOP ]
         [INNERGRID, [ 0, 0 ], [ -1, -1 ], 0.25, black ]
         [ROWBACKGROUNDS, [0, 0], [-1, -1], [white,#E0E0E0]]
         [BOX, [ 0, 0 ], [ -1, -1 ], 0.25, black ]

Behind the scenes, rst2pdf uses ReportLab to create the PDF. The commands style maps directly to ReportLab’s TableStyle commands (section 7.4 of the current documentation)

Each command contains an identifier, the start and stop cell definition to which it applies and then the style to apply. The cell definition is defined as [X,Y] where [0,0] is the top left cell, [2,3] would be the cell with e in it in the definition above. Negative numbers count from the bottom right, so [-1,-1] is the bottom-right corner.

Key options:

The style for the table heading is called table-heading:

    table-heading:
        parent : heading
        backColor : beige
        alignment : TA_CENTER
        valign : BOTTOM
        borderPadding : 0

These settings should be obvious. I always override backColor!

The style for the table elements is table-body:

table-body:
      parent : normal

By default, it isn’t styled, but if you want to change the textColor, this is where to do it.

Overriding on a per table basis

To override for a specific table, then set a class before the table:

.. class:: mytable

+-----------+-----------+-----------+
| Heading 1 | Heading 2 | Heading 3 |
+===========+===========+===========+
| a         | b         | c         |
|           |           |           |
| aa        |           |           |
+-----------+-----------+-----------+
| d         | e         | f         |
+-----------+-----------+-----------+

The most common reason to do this is to set up specific column widths:

    mytable:
        parent: table
        colWidths: [3cm, 6cm, 3cm]

This is mostly useful when the auto-sizing routine causes odd line breaks in heading text.

If you are targeting rst2pdf, then you can also set widths using the .. widths:: directive like this:

.. widths:: 20 20 60

+-----------+-----------+-----------+
| Heading 1 | Heading 2 | Heading 3 |
+===========+===========+===========+
| a         | b         | c         |
+-----------+-----------+-----------+
| d         | e         | f         |
+-----------+-----------+-----------+

The width numbers are percentages and it only works if you pass the command line option -e preprocess when compiling.

My defaults

My defaults currently are:

styles:
    table:
        commands: []
            [VALIGN, [ 0, 0 ], [ -1, -1 ], MIDDLE ]
            [ROWBACKGROUNDS, [0, 0], [-1, -1], [white]]
            [LINEBELOW, [0, 0], [-1, 0], 0.5, black]
            [BOTTOMPADDING, [0, 1], [-1, -1], 5]
            [TOPPADDING, [0, 1], [-1, -1], 5]
            [ALIGN, [ 0, 0 ], [ -1, -1 ], LEFT ]


    table-heading:
        parent : heading
        fontName: stdBold
        backColor : white
        alignment : TA_LEFT

This results in the very simple table style of:

This suits me as a starting point.