Tables (+) reStructuredText

atorin — Mon, 19 Mar 2018 21:32:58 +0000

This post is an extract from a post I published on my personal blog.

What's inside

RST + Tables + Vim
Sphinx + Tables + PDF output
HTML Table -> RST Table

RST + Tables + Vim

I love Vim (actually, MacVim), and as soon as I started working with reStructuredText (RST) documents for the first time, I hoped to find a nice plug-in to speed up my editing. Creating tables manually was particularly painful!

Of course, someone had already figured out a solution to that... Enter Riv!

Riv is a great plug-in, with many shortcuts to make your life easier when dealing with RST files. In my opinion, the best thing about Riv is how it handles table creation. You create cells by simply pressing tab, and when you modify the content, the table automagically reshapes when you exit the edit mode.

A few shortcuts for you (on MacOS):

tab: move to the next cell
option + enter: create the header row
control + enter: create a new regular row

If you try Riv, don't forget to install InstantRst as well. This will enable a live preview in the browser, as you edit your document.

Sphinx + Tables + PDF output

If you write technical documentation, sooner or later you're bound to stumble on Sphinx and Read the Docs.

Tables in Sphinx can be a very frustrating thing (see above!). Sometimes you have a large table that is difficult to render with the RST syntax; in other cases, the table looks good in the HTML page but awful in the PDF output.

For those cases, I have created a short tutorial about tables with Sphinx.

One of the best options, in my option, is to work with CSV tables. You can create your table in a spreadsheet, without the need to worry about the proper formatting in RST.

To take care of the PDF output for those long tables that won't fit on a single page, you can use the longtable class. Then, with the tabularcolumns directive, you can control the width of the columns in your PDF.

This is a sample code snippet to render a table from a CSV file with two columns. Check the result in the tutorial.

   .. tabularcolumns:: |p{1cm}|p{7cm}|

   .. csv-table:: Caption of the table
      :file: path-to-the/file.csv 
      :header-rows: 1 
      :class: longtable
      :widths: 1 1

This approach also works if you use a grid table (the type of tables shown in the GIF above) instead of a CSV table, with the proper changes.

HTML Table -> RST Table

Speaking of tables, if you start from a table in HTML, you can use DashTable to convert it to RST.

This tool will produce for you a nice grid table that you can easily copy and paste in your RST document.

DEV Community: atorin

Tables (+) reStructuredText

What's inside

RST + Tables + Vim

Sphinx + Tables + PDF output

HTML Table -> RST Table