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
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.
- column span
With the role
cspana cell can be extended through additional columns.
- row span
With the role
rspana 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-cellsthis behaviour can be changed from auto span to auto fill, which automatically inserts (empty) cells instead of spanning the last cell.
.. 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:
Then add the extension to the list of extensions in your Sphinx project's
After this, you can use the
flat-table directive in your reStructuredText files.
The LinuxDoc library contains Sphinx extensions and command-line tools to extract documentation from C/C++ source file comments. Although the project was started for the Linux kernel documentation, the extensions are interesting enough for other applications as well.