1.12. Tables

For more details, see Table in Docutils or Tables Basics and Tables Directives.

.. table::

The .. table:: directive serves as optional wrapper of the Grid Style and Simple Style.

.. tabularcolumns::

The .. tabularcolumns:: directive gives a column spec for the next table occurring in the source file. The spec is the second argument to the LaTeX tabulary package’s environment (which Sphinx uses to translate tables). For more details, see tabularcolumns.

1.12.1. Grid Style

For more details, see Grid Tables in Docutils.

the example

.. tabularcolumns:: p{0.132\linewidth}p{0.198\linewidth}p{0.330\linewidth}
.. table:: Example table in grid style
   :name: tables-grid-example
   :widths: 20, 30, 50
   :class: longtable
   :align: center
   :width: 66%

   +------------+------------+-----------+
   | Header 1   | Header 2   | Header 3  |
   +============+============+===========+
   | body row 1 | column 2   | column 3  |
   +------------+------------+-----------+
   | body row 2 | Cells may span columns.|
   +------------+------------+-----------+
   | body row 3 | Cells may  | - Cells   |
   +------------+ span rows. | - contain |
   | body row 4 |            | - blocks. |
   +------------+------------+-----------+

which gives

Table 1.4 Example table in grid style

Header 1	Header 2	Header 3
body row 1	column 2	column 3
body row 2	Cells may span columns.
body row 3	Cells may span rows.	Cells contain blocks.
body row 4

1.12.2. Simple Style

For more details, see Simple Tables in Docutils.

the example

.. tabularcolumns:: p{0.132\linewidth}p{0.198\linewidth}p{0.330\linewidth}
.. table:: Example table in simple style
   :name: tables-simple-example
   :widths: 20, 30, 50
   :align: center
   :width: 66%

   ====== ====== ======
       Inputs    Output
   ------------- ------
   A      B      A or B
   ====== ====== ======
   False
   --------------------
   True
   --------------------
   True   False  True
   ------ ------ ------
   False  True
   ====== =============

which gives

Table 1.5 Example table in simple style

Inputs		Output
A	B	A or B
False
True
True	False	True
False	True

1.12.3. List Table

.. list-table::

For more details, see List Tables in Docutils.

Hint

For table content that needs a higher complexity than the list table is able to support use the flat-table.

The example

.. tabularcolumns:: p{0.132\linewidth}p{0.198\linewidth}p{0.330\linewidth}
.. list-table:: Example list table
   :name: tables-list-example
   :widths: 20, 30, 50
   :class: longtable
   :header-rows: 1
   :align: center
   :width: 66%

   * - Treat
     - Quantity
     - Description
   * - Albatross
     - 2.99
     - On a stick!
   * - Crunchy Frog
     - 1.49
     - If we took the bones out, it would not be
       crunchy, now would it?
   * - Gannet Ripple
     - 1.99
     - On a stick!

Which gives

Table 1.6 Example list table

Treat	Quantity	Description
Albatross	2.99	On a stick!
Crunchy Frog	1.49	If we took the bones out, it would not be crunchy, now would it?
Gannet Ripple	1.99	On a stick!

1.12.4. CSV Table

.. csv-table::

For more details, see CSV Tables in Docutils.

Hint

In almost all cases, csv-table is the easiest and most maintainable way to insert a table into a document. It should be preferred unless there is a compelling reason to use one of the other styles.

The example

.. tabularcolumns:: p{0.132\linewidth}p{0.198\linewidth}p{0.330\linewidth}
.. csv-table:: Example CSV table
   :name: tables-csv-example
   :header: "Treat", "Quantity", "Description"
   :widths: 20, 30, 50
   :class: longtable
   :align: center
   :width: 66%

   "Albatross", 2.99, "On a stick!"
   "Crunchy Frog", 1.49, "If we took the bones out, it would not be
   crunchy, now would it?"
   "Gannet Ripple", 1.99, "On a stick!"

Which gives

Table 1.7 Example CSV table

Treat	Quantity	Description
Albatross	2.99	On a stick!
Crunchy Frog	1.49	If we took the bones out, it would not be crunchy, now would it?
Gannet Ripple	1.99	On a stick!

Some of the options recognized are:

:widths:

Contains a comma or space-separated list of relative column widths. The default is equal-width columns.

The special value auto may be used by writers to decide whether to delegate the determination of column widths to the backend.

In most cases, the best result is either the default or auto. If you’re unsure, try it both ways and see which looks better to you.

:header:

Contains column titles. It must use the same CSV format as the main CSV data.

:delim:

Contains a one character string used to separate fields. Default value is comma. It must be a single character or Unicode code.

The only reason to use something other than a comma is when copying large blocks of content from another source that uses a different style. If you are creating new table content yourself, use the comma.

The example

.. csv-table:: Example CSV table with customized delimiter
   :name: tables-csv-delim-example
   :header: "Name", "Password"
   :widths: auto
   :delim: :
   :align: center
   :width: 66%

   "Peter":":literal:`QW8rTn@*emk;=J3f`"
   "Paul":":literal:`b3%C/-9\`][cnG,;{`"

Which gives

Table 1.8 Example CSV table with customized delimiter

Name	Password
Peter	QW8rTn@*emk;=J3f
Paul	b3%C/-9`][cnG,;{

:align:

It specifies the horizontal alignment of the table. It can be left, right or center.

The example

.. csv-table:: Example CSV table with right alignment
   :name: tables-csv-align-example
   :header: "Name", "Password"
   :delim: #
   :align: right

   "Peter"#":literal:`QW8rTn@*emk;=J3f`"
   "Paul"# ":literal:`b3%C/-9\`][cnG,;{`"

Which gives

Table 1.9 Example CSV table with right alignment

Name	Password
Peter	QW8rTn@*emk;=J3f
Paul	b3%C/-9`][cnG,;{

:url:

Contains an Internet URL reference to a CSV data file.

:file:

Contains the local file system path to a CSV data file.

The example

.. csv-table:: Example CSV table from source file
   :name: tables-csv-srcfile-example
   :file: example.csv
   :delim: |
   :encoding: utf-8-sig
   :header-rows: 1
   :stub-columns: 1
   :width: 66%

Which gives

Table 1.10 Example CSV table from source file

Name	Password
Peter	QW8rTn@*emk;=J3f
Paul	b3%C/-9`][cnG,;{

Which needs

The example above processed the following CSV file content:

Listing 1.1 CSV example file (tables/csv/srcfile/example.csv)

Name|Password
Peter|:literal:`QW8rTn@*emk;=J3f`
Paul|:literal:`b3%C/-9\`][cnG,;{`

Note

There is no support for checking that the number of columns in each row is the same. However, this directive supports CSV generators that do not insert “empty” entries at the end of short rows, by automatically adding empty entries.