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.