Use list table to display a table with reStructuredText.

Photo by Scott Webb on Unsplash

Anyone who has already maintained a table in reStructuredText know that, it is not easy. Especially, if it’s a table with many data. Fortunately a solution exist, to simplify the maintenance of a table. The list-table directive is used to create a table from data in a uniform bullet list. The display result is the same of a normal table.

The default behavior to maintain a table with reStructuredText is an ascii table. A little example here:

.. table::
+---------+----------+----------+
| Column 1| Column 2 | Column 3 |
+=========+==========+==========+
| Row     | Value 1  | Value 2  |
+---------+----------+----------+

It’s beautiful and close of the final display, but it’s also hard to maintain. Imagine if you need to add one new row or a new column. Imagine if you need to rename a column or modify few values in the table. That will be long to make. If you change a value you will probably adapt the signs.

Now, we go see the same little example with list-table directive:

.. list-table::
* - Column 1
  - Column 2
  - Column 3
* - Row
  - Value 1
  - Value 2

You have more lines to generate the table, but it’s also more easy to maintain. You concentrate only on the data, not on the table display. You use the list system to generate the table. Imagine if you need to add one new row or a new column. Imagine if you need to rename a column or modify few values in the table. That will be fast and easy. It’s not necessary to adapt the signs, you modify only the necessary value.

How we can migrate the table? We can simply made this manually, but again that can be long and is not fun to make that. Luckily a solution exist, Rackspace have made a script for that. First, you need get the repository:

git clone https://github.com/rackerlabs/docs-rackspace.git
cd docs-rackspace

Now, you can try to migrate the table of a file:

python tools/table.py /path/to/file

By default the result is display in the stdout and the file is not rewrite. To rewrite the file we can use the -r or — replace option:

python tools/table.py -r /path/to/file

If we prefer and to prevent data loss, we can use the -c or — create option and confirm the conversion is correct before removing the original source file:

python tools/table.py -c /path/to/file

We can find more information in the documentation of the project.

I have made a patch in TripleO project to use list-table directive. It’s not a good example because the patch was refused. The new format added too much line. In this case, I think the problem is not the directive because the table also unsatisfactory. I think, the project must used another solution to display the data. Feel free to propose a solution if anyone have an idea for manage this case.

Another solution to generate your table with reStructuredText format. The directive is not perfect, but I think is more easy to use.