Adding images to a csv-table in restructured text

Anyone who has tried to add images using the csv-table directive in restructured text may have come to the following conclusion: it can’t be done. Well certainly not using any of the existing attributes or syntax for tables (an oversight?), but it can be done with the replacement directive.

Firstly, a csv-table in restructured text looks like this:

Currently Held Records

No	Category	Details	Record	Date	Photo
1	Somersaulting	Longest continuous distance	12 miles 390 yards	Apr 1986

And would created with the following code:

.. csv-table:: Currently Held Records
  :header: "No", "Category", "Details", "Record", "Date", "Photo"
  :widths: 42, 270, 270, 220, 119, 119

  1, "**Somersaulting**", "Longest continuous distance", "12 miles 390 yards", "Apr 1986", |green_face.jpg|

Ignore the first three lines—it’s the table structure info, similar to the way you would define an image, but instead defining table column titles and widths. Should be pretty obvious how to change anything there, but in case not, let’s recap a few csv-table fundamentals, as it is important in restructed text that formatting is followed precisely—right down to the space and comma:

• a single space after each comma—no other spaces
• bold text like **this**
• all text inside "quote marks"
• numbers don’t need to be in quote marks, unless together with text: "12 miles 390 yards"
• return at the end of the line

The last line is an example of a row of the table, and more importantly contains the image:

1, "**Somersaulting**", "Longest continuous distance", "12 miles 390 yards", "Apr 1986", |green_face.jpg|

The image is the complex, for “|green_face.jpg|” (without quotes) is actually a “replacement” for the image definition, somewhat akin to an ID in css or a variable in pretty much any programming language you could name.

The image url, link and any other image parametres pointed to by the replacement id then get defined below the table (ie at the bottom of your reSt document):

.. |green_face.jpg| image:: green_face.jpg
  :target: green_face.jpg

Note:

• The spaces are important as usual, as is putting the info on two lines
• the name of the replacement/id can be anything, but it makes sense to me to use the image name
• you can use the same image two times (or more) but only define the replacement once.