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 acolumn spec
for the next table occurring in the source file. The spec is the second argument to the LaTeXtabulary
package’s environment (which Sphinx uses to translate tables). For more details, seetabularcolumns
.
1.12.1. Grid Style¶
For more details, see Grid Tables in Docutils.
- the example
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19
.. 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
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20
.. 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
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22
.. 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
1 2 3 4 5 6 7 8 9 10 11 12 13
.. 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
1 2 3 4 5 6 7 8 9 10
.. 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
orcenter
.- The example
1 2 3 4 5 6 7 8
.. 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
1 2 3 4 5 6 7 8
.. 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:
1 2 3
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.