rst-table-span 1.0.0

Support for colspan and rowspan in RST tables for docutils and Sphinx

reStructuredText provides four syntaxes for tables:

• Grid tables

• Simple tables

• List tables

• CSV tables

However, only grid and simple tables support cells spanning multiple columns, and only grid tables support cells spanning multiple rows.

The rst-table-span package adds the :colspan:`C`, :rowspan:`R`, and :cellspan:`CxR` roles which add support for column and row span to all existing RST table types.

This project was inspired by the flat-table directive from the LinuxDoc project.

Example

To produce a table like this:

Header row, column 1 (header rows optional)	Header 2	Header 3	Header 4
body row 1, column 1	column 2	column 3	column 4
body row 2	Cells may span columns.
body row 3	Cells may span rows.	Corner
body row 4

You would normally need to write this:

+------------------------+------------+----------+----------+
| 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  | Corner              |
+------------------------+ span rows. |                     |
| body row 4             |            |                     |
+------------------------+------------+---------------------+

But with rst-table-span you can instead write it using a csv-table:

.. csv-table::
   :header-rows: 1

   "Header row, column 1 (header rows optional)", Header 2, Header 3, Header 4
   "body row 1, column 1", column 2, column 3, column 4
   body row 2, :colspan:`3` Cells may span columns.
   body row 3, :rowspan:`2` Cells may span rows., :cellspan:`2x2` Corner
   body row 4

Or a list-table:

.. list-table::
   :header-rows: 1

   * - Header row, column 1 (header rows optional)
     - Header 2
     - Header 3
     - Header 4
   * - body row 1, column 1
     - column 2
     - column 3
     - column 4
   * - body row 2
     - :colspan:`3` Cells may span columns.
     -
     -
   * - body row 3
     - :rowspan:`2` Cells may span rows.
     - :cellspan:`2x2` Corner
     -
   * - body row 4
     -
     -
     -

Installation and Usage

Install the package using pip:

pip install rst-table-span

or add the rst-table-span package to your project or environment dependency list (eg. pyproject.toml, requirements.txt, or similar).

Sphinx

Also add the rst_table_span module to your list of extensions in your conf.py settings:

extensions = [
    "rst_table_span",
]

Docutils

Docutils doesn’t provide a declarative extension mechanism, as far as I know. If you invoke docutils programatically using its Publisher API, then a global function is provided to register the roles. Call it before setting up the publisher:

import sys
import docutils.__main__
import rst_table_span

rst_table_span.register_docutils_roles()
sys.exit(docutils.__main__.main())

For convenience, this package installs the above script as the rst-table-span-docutils executable. It behaves the same way as the standard docutils executable. It can then be used used like this:

rst-table-span-docutils demo.rst --output demo.html

License

This library is released under the MIT license (see the LICENSE file in the source code).