CSV Tables

.. csv-table:: specifies a table as CSV data rather than character-art or a nested bullet list. It shares every presentation option with .. list-table:: — the two parse into the same node and render through the same code — and adds its own options for where the data comes from and how it is tokenized.

Cell content is parsed as full block-level RST, exactly like a grid table cell.

Basic CSV Table

Table with a Title

The directive's argument, if given, becomes the table's caption:

:header-rows:

Marks the leading N rows of the data as header rows, rendered inside <thead>:

:header:

Supplies header rows as CSV data in the option itself, so the body holds only the table's real data. They are prepended to the rows and counted as header rows automatically:

:header: and :header-rows: add up — the table below has two header rows, one from each:

:stub-columns:

Marks the leading N columns as stub (row-header) columns in every row, rendered as <th scope="row">:

:widths:

Sets relative column widths — auto and grid both let the renderer decide, while an explicit list of integers is normalized into percentages:

:width:

Sets the overall table width:

:align:

Aligns the table on the page — left, center, or right:

:class:

Adds extra CSS classes to the rendered <table>, after the csv-table class the directive always carries:

:name: and Cross-Referencing

Gives the table a hyperlink target, referenceable via :ref:. As with any other internal target in rinx today, the link resolves to this document, not precisely to the table itself.

See fruit-csv-table for the fruit table above.

Quoting

A field wrapped in double quotes may contain the delimiter, a doubled quote (which stands for one literal quote), and even line breaks:

:delim:

Changes the field delimiter. It accepts a literal character, the words space and tab, or a character code such as 0x3B:

:quote:

Changes the quoting character:

:escape:

Sets an escape character, an alternative to doubling the quote:

:keepspace:

By default the whitespace following a delimiter is stripped. :keepspace: keeps it in the field text:

:file:

Reads the data from a file instead of the directive body. The path resolves relative to this document, and the file must be declared in the library's csv_data attribute in BUILD.bazel so it reaches the parse action:

Ragged Rows

A row with fewer fields than the widest row is padded with empty cells rather than rejected:

RST Inside a Cell

Every field is reparsed as block-level RST, so inline markup, literals and cross-references all work inside a cell: