Create data tables¶

The starter pack can render comma-separated values (CSV) data as tables.

For other table types, see tables in reStructuredText and tables in MyST.

Create a table from inline data¶

If you have a small amount of CSV data, you can include the data in the doc source. For example:

Table

Animal	Number of legs	Size
Worm	0	Small
Penguin	2	Medium
Horse	4	Large
Ant	6	Small
Octopus	8	Medium

reST

.. csv-table::
   :header: "Animal", "Number of legs", "Size"

   "Worm", 0, "Small"
   "Penguin", 2, "Medium"
   "Horse", 4, "Large"
   "Ant", 6, "Small"
   "Octopus", 8, "Medium"

If the table needs it, customize the column widths, character encoding, and so on, as described in the csv-table reference.

MyST

```{csv-table}
:header: "Animal", "Number of legs", "Size"

"Worm", 0, "Small"
"Penguin", 2, "Medium"
"Horse", 4, "Large"
"Ant", 6, "Small"
"Octopus", 8, "Medium"
```

If the table needs it, customize the column widths, character encoding, and so on, as described in the csv-table reference (MyST).

Create a table from a CSV file¶

If you have a large amount of CSV data, or the data is generated by an automated process, you can include the data from a file. For example:

Table

Animal	Number of legs	Size
Worm	0	Small
Penguin	2	Medium
Horse	4	Large
Ant	6	Small
Octopus	8	Medium

reST

.. csv-table::
   :file: /reuse/animals.csv
   :header-rows: 1

MyST

```{csv-table}
:file: /reuse/animals.csv
:header-rows: 1
```

docs/reuse/animals.csv

"Animal", "Number of legs", "Size"
"Worm", 0, "Small"
"Penguin", 2, "Medium"
"Horse", 4, "Large"
"Ant", 6, "Small"
"Octopus", 8, "Medium"

Create an interactive table¶

The Sphinx DataTables extension enables interactive tables. Users can sort columns and filter rows. For examples, see the extension’s documentation.

The extension isn’t available by default in the starter pack.

To include the extension in your documentation, add sphinx-datatables to docs/requirements.txt. Then add sphinx_datatables to the extensions list in docs/conf.py.

Make a table interactive by adding a special CSS class to the directive:

reST

.. csv-table::
   :class: sphinx-datatable
   :file: /reuse/animals.csv
   :header-rows: 1

MyST

```{csv-table}
:class: sphinx-datatable
:file: /reuse/animals.csv
:header-rows: 1
```