Using reStructuredText - Tables

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:: User list with two persons
   :name: table-user-list-with-two-persons-ref

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

And you can cross-reference to the Table 1 in the text, using:

:numref:`table-user-list-with-two-persons-ref`

List-table directive

Note

This is the recommended option for simple tables.

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

.. list-table:: Another 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:

Table 2 Another 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 Another user list table, we only have two users.

Same as before, you can also use just a numbered reference Table 2:

you can also use just a numbered reference :numref:`a-name-you-can-use-to-link-to-this-table`

CSV-table directive

Note

This is the recommended option for long tables, specially using a separate CSV file.

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

.. csv-table:: User list
   :name: this-one-is-a-csv-table-with-a-user-list
   :header: "First name","Last name"

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

This is the result:

Table 3 User list

First name	Last name
John	Doe
Jane	Dove

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

.. csv-table:: 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 (EFTA countries.):

Table 4 EFTA countries.

Country Code	Country Name
IS	Iceland
LI	Liechtenstein
NO	Norway
CH	Switzerland