Using flat tables in reStructuredText with Sphinx for column and row spans

The reStructuredText markup language has various types of tables. One of these is the list-table, which you create from a two-level bullet list. For instance, this is how you create a list table of the six I/O combinations of Bluetooth Low Energy devices:

.. list-table:: Input and output capabilities
   :header-rows: 1
   :stub-columns: 1

   * -
     - No output
     - Numeric output
   * - No input
     - NoInputNoOutput
     - DisplayOnly
   * - Yes/No
     - NoInputNoOutput
     - DisplayYesNo
   * - Keyboard
     - KeyboardOnly
     - KeyboardDisplay

The first level of bullets lists the rows of the table, while the second level of bullets list the cells in each column of that row. With the header-rows and stub-colums options you specify the number of rows and columns that are rendered in bold.

Sphinx renders this list table like this:

I like list tables and I've used them a lot in my books, but they have some limitations. For instance, you can't extend a cell through additional columns or rows. You can create empty cells (like I did in the previous example), but if you would create multiple empty cells next to each other, they aren't merged, but still rendered as separate cells.

Enter the flat-table. This is part of the LinuxDoc extension for Sphinx. [1] A flat table is just like a list table, but with some additional features:

column span

With the role cspan a cell can be extended through additional columns.

row span

With the role rspan a cell can be extended through additional rows.

auto span

The rightmost cell of a table row will automatically be extended over the missing cells on the right side of that table row. With the option fill-cells this behaviour can be changed from auto span to auto fill, which automatically inserts (empty) cells instead of spanning the last cell.

An example:

.. flat-table:: Characteristics of the BLE badge
   :header-rows: 1

   * - Service
     - Characteristic
     - Properties
   * - :rspan:`2` 0xfee7
     - 0xfec7
     - WRITE
   * - 0xfec8
     - INDICATE
   * - 0xfec9
     - READ
   * - 0xfee0
     - 0xfee1
     - NOTIFY, READ, WRITE

Sphinx renders this flat table like this:

As you can see, the cell with 0xfee7 extends through the two next rows, thanks to the :rspan:`2` role. Then in the bullets of the next two rows, you just drop the bullet for the cell that would come on that place. That's why the next two rows only have two bullets, while the last row has three bullets again for the three columns.

If you want to use the flat table with Sphinx, install the linuxdoc Python package:

pip3 install linuxdoc

Then add the extension to the list of extensions in your Sphinx project's conf.py:

extensions = [
  ...
  'linuxdoc.rstFlatTable'
]

After this, you can use the flat-table directive in your reStructuredText files.