Search code examples
restructuredtext

Vertical headers in RestructuredText tables


In RestructuredText, you can render a header row in a table like this (taken from the documentation :

+------------------------+------------+----------+----------+
| Header row, column 1   | Header 2   | Header 3 | Header 4 |
| (header rows optional) |            |          |          |
+========================+============+==========+==========+
| body row 1, column 1   | column 2   | column 3 | column 4 |
+------------------------+------------+----------+----------+
| body row 2             | Cells may span columns.          |
+------------------------+------------+---------------------+
| body row 3             | Cells may  | - Table cells       |
+------------------------+ span rows. | - contain           |
| body row 4             |            | - body elements.    |
+------------------------+------------+---------------------+

Is it possible to do the something similar with the first column? An example, which clearly doesn't work, could be the following (note the double like at the end of column 1):

+------------------------++------------+----------+----------+
| Header row, column 1   || Header 2   | Header 3 | Header 4 |
| (header rows optional) ||            |          |          |
+========================++============+==========+==========+
| body row 1, column 1   || column 2   | column 3 | column 4 |
+------------------------++------------+----------+----------+
| body row 2             || Cells may span columns.          |
+------------------------++------------+---------------------+
| body row 3             || Cells may  | - Table cells       |
+------------------------++ span rows. | - contain           |
| body row 4             ||            | - body elements.    |
+------------------------++------------+---------------------+

Solution

  • You may achieve this using list-table directive with option stub-columns. Or, you may even combine stub-columns with header-rows. See the http://docutils.sourceforge.net/docs/ref/rst/directives.html#list-table for the details. Hereafter is a simple example:

    .. list-table:: Sample list table
       :widths: 10 20 20
       :header-rows: 1
       :stub-columns: 1
    
       * - 
         - Column 1
         - Column 2
       * - Row 1
         - Hello
         - World!
       * - Row 2
         - Hello
         - List Table!
       * - Row 3
         - This
         - Works
    

    An obvious disadvantage is that you need to maintain table content as a list, which may be not that much convenient as with regular simple tables. So, you might want to check out the csv-table directive here: https://docutils.sourceforge.io/docs/ref/rst/directives.html#csv-table-1, which also has option stub-columns.

    If you need to stick to regular tables syntax - sorry, I'm not sure this is possible. As a workaround - you can use strong emphasis for text in the first column :-)