reStructuredText tables¶

reStructuredText draws a table in two plain-text forms, the grid table and the simple table, and builds one from data with three directives: list-table from a nested list, csv-table from comma-separated values, and table, which gives a drawn table a title and options. ubCode renders all five in the editor preview and in its html and pdf builds.

Grid tables¶

A grid table is drawn with +, - and |; a row of = ends the header rows. A cell can span columns or rows, and hold any block content, a list for instance.

reStructuredText

A grid table

+-------------+---------------------------------+
| Directive   | What it builds a table from     |
+=============+=================================+
| list-table  | a two-level bullet list         |
+-------------+---------------------------------+
| csv-table   | comma-separated values,         |
|             | written inline or read from a   |
|             | file                            |
+-------------+---------------------------------+
| Both take a title, ``:header-rows:`` and      |
| ``:widths:``.                                 |
+-----------------------------------------------+

Directive	What it builds a table from
list-table	a two-level bullet list
csv-table	comma-separated values, written inline or read from a file
Both take a title, `:header-rows:` and `:widths:`.

MyST

MyST has no grid table; its plain table is the pipe table (live in the MyST pipe table).

Simple tables¶

A simple table is drawn with rows of = alone: one above the table, one under the header, one below the table. Each column’s text sits between the gaps in those rows, and a row of - under a header cell joins the columns it spans.

reStructuredText

A simple table

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

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

MyST

MyST has no simple table; its plain table is the pipe table (live in the MyST pipe table).

List tables¶

The list-table directive builds a table from a two-level bullet list: each outer item is a row, and each inner item a cell. Its argument is the table’s title.

reStructuredText

A list table

.. list-table:: Builders
   :header-rows: 1
   :widths: 1 2

   * - Builder
     - Writes
   * - ``ubc build html``
     - A static site.
   * - ``ubc build pdf``
     - One PDF file.

Builders¶
Builder	Writes
`ubc build html`	A static site.
`ubc build pdf`	One PDF file.

MyST

```{list-table} Builders
:header-rows: 1
:widths: 1 2

* - Builder
  - Writes
* - `ubc build html`
  - A static site.
* - `ubc build pdf`
  - One PDF file.
```

The MyST form renders live in the MyST list table.

list-table, csv-table and table take these options:

:header-rows: / :stub-columns:: How many leading rows are header rows, and how many leading columns are row headers (table reads the header from its drawn table instead).
:widths:: One positive whole number per column, read as relative shares, or auto (and, on table only, grid).
:width:: The width of the whole table, a number with a unit or a percentage.
:align:: left, center or right (not yet applied by ubc build html; see the table differences).
:class: / :name:: Extra CSS classes, and an identifier for the table.

A title’s inline markup is rendered; what ubCode reports for a malformed :widths: or :width: is in the table differences.

CSV tables¶

The csv-table directive builds a table from comma-separated values, written in its body or read from the file its :file: option names (relative to the document, or to the source directory when it starts with /). :header: gives a header row of its own.

reStructuredText

CSV tables

.. csv-table:: Written inline
   :header: Format, Suffix

   "reStructuredText", ".rst"
   "Markdown (MyST)", ".md"

.. csv-table:: Read from a file
   :file: /../specimens/tables/builders.csv
   :header-rows: 1

Written inline¶
Format	Suffix
reStructuredText	.rst
Markdown (MyST)	.md

Read from a file¶
Builder	Command	Output
Sphinx	sphinx-build -b html	A site
ubCode	ubc build html	A site
ubCode	ubc build pdf	One PDF file

MyST

```{csv-table} Written inline
:header: Format, Suffix

"reStructuredText", ".rst"
"Markdown (MyST)", ".md"
```

```{csv-table} Read from a file
:file: /../specimens/tables/builders.csv
:header-rows: 1
```

The MyST form renders live in the MyST CSV tables.

:delim:, :quote:, :escape: and :keepspace: set the CSV dialect (:delim: tab and :delim: space name the two blank delimiters). :url: is refused: ubCode builds read no table data from the network.

Titled tables¶

The table directive wraps a grid or simple table to give it a title and the options above.

reStructuredText

A titled table

.. table:: Markup and suffix

   ================  ======
   Markup            Suffix
   ================  ======
   reStructuredText  .rst
   MyST              .md
   ================  ======

Markup and suffix¶
Markup	Suffix
reStructuredText	.rst
MyST	.md

MyST

```{table} Markup and suffix

| Markup           | Suffix |
|------------------|--------|
| reStructuredText | .rst   |
| MyST             | .md    |
```

The MyST form renders live in the MyST titled table. In MyST the table inside is a pipe table.