Tables

Tip

Go directly to the recommended options:

list-table
csv-table
xlsx-table

Grid tables

The reStructuredText markup supports two basic types of tables. For grid tables, you have to “paint” the cell grid yourself. They look like 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             | ...        | ...      |          |
+------------------------+------------+----------+----------+

This is the result:

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	…	…

Simple tables

Simple tables are easier to write, but limited: they must contain more than one row, and the first column cannot contain multiple lines. They look like this:

=====  =====  =======
A      B      A and B
=====  =====  =======
False  False  False
True   False  False
False  True   False
True   True   True
=====  =====  =======

This is the result:

A	B	A and B
False	False	False
True	False	False
False	True	False
True	True	True

Table directive

The table directive associates a title with the following table:

.. table:: Table 1 - User list with two persons

   ==========  =========
   First name  Last name
   ==========  =========
   John        Doe
   Jane        Dove
   ==========  =========

This is the result:

Table 1 - User list with two persons
First name	Last name
John	Doe
Jane	Dove

List-table directive

A list-table is created from a uniform two-level bullet list:

.. list-table:: User list
   :header-rows: 1
   :name: a-name-you-can-use-to-link-to-this-table
   :widths: 10 20 10
   :width: 50%
   :align: center

   *  - First name
      - Last name
      - Photo
   *  - John
      - Doe
      - .. image:: img/john.png
   *  - Jane
      - Dove
      - .. image:: img/jane.png

This is the result:

User list
First name	Last name	Photo
John	Doe
Jane	Dove

And this is how you reference the table in your text:

As you can see in the :ref:`a-name-you-can-use-to-link-to-this-table` table, we only have two users.

Which generates the following paragraph:

As you can see in the User list table, we only have two users.

CSV-table directive

A csv-table is created from comma-separated values (either in the document or in an external file):

.. csv-table:: User list
   :header: "First name","Last name"

   "John","Doe"
   "Jane","Dove"

This is the result:

User list
First name	Last name
John	Doe
Jane	Dove

Another example of csv-table, using and external file:

.. csv-table:: Table 1 - EFTA countries.
   :name: the-EFTA-table
   :file: tables/EFTA.csv
   :header-rows: 1
   :stub-columns: 1

This is the result that you can link to using the name you gave it (Table 1 - EFTA countries.):

Table 1 - EFTA countries.
Country Code	Country Name
IS	Iceland
LI	Liechtenstein
NO	Norway
CH	Switzerland

Links