Search code examples
python-sphinxrestructuredtext

Smart tables for Sphinx (reStructuredText)

Are there any smart table extensions for using tables in RST?

It is too tedious to use tables with multiple columns having to type each row and column. Especially if I want to merge or split the cells in the table as shown below:

enter image description here

I am trying to get the above table using flat-table. Can anyone suggest on how to get this?

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

   * - Col 1
     - Col 2
     - Col 3
   * - :rspan:`2` 0xfee7
     - 0xfec7
     - WRITE
   * - 0xfec8
     - INDICATE
   * - 0xfec9
     - READ
   * - 0xfee0
     - 0xfee1
     - NOTIFY, READ, WRITE

Using the Linuxdoc extension to use the flat-tables.

Solution

  • First, install the linuxdoc Python package:

    pip install linuxdoc

    Next, add linuxdoc.rstFlatTable to the list of extensions in your Sphinx project's conf.py:

    extensions = [
    'linuxdoc.rstFlatTable',
]

    The linuxdoc manual contains an example that features combinations of row and column spans.

    The following reStructuredText produces your table:

    .. flat-table:: Spanning table cells
   :header-rows: 2

   * - :rspan:`1` Col 1
     - :rspan:`1` Col 2
     - :rspan:`1` Col 3
     - :cspan:`2` Col 4

   * - Col 4a
     - Col 4b
     - Col 4c

   * - 1
     - 2
     - 3
     - 4a
     - 4b
     - 4c

    Note that if you set header-rows option to 1, linuxdoc produces a malformed table.