sphinx-tabular 0.2.3

Sphinx directives for CSV-powered tabular authoring.

sphinx-tabular

Full documentation

Instead of just modifying the final table output, sphinx-tabular builds real docutils table nodes (table/tgroup/row/entry) the same way docutils' own table directives do, and only overrides the HTML rendering of table cells (for colspan/rowspan/inline styling) — the rest of the output is generated by Sphinx's normal HTML writer.

While the table structure and merged cells will work in the LaTeX builder PDF output, the table formatting (colors, icons, bacgkround color, text color, and alignment) is HTML only.

Donations to help support this project...

Venmo

Features

• Sphinx extension.
• Uses standard CSV file format.
• Easily merge table cells with < and ^.
• Support reStructuredText and Markdown.
• Support for inline table data and external files.
• Optional sticky header support for one or more header rows.
• Provides a minimal set of spreadsheet formulas.
• Set table cell alignment and per-cell alignment in both horizontal and vertical directions.
• Set custom cell text and background colors.
• Custom status pill.
• Support for Font Awesome and Bootstrip icons if installed by your theme.
• Sortable rows by clicking on the header row.
• Searchable option.

Installation

pip install sphinx-tabular

conf.py

bash extensions = [ ..., 'sphinx_tabular', ..., ]

Directives

RST, external file:

RST .. rcsv-table:: Title :file: table.rcsv

RST, inline data.

``RST .. rcsv-table:: Title

Col 1, Row 1
Col 2, Row 2

``

Markdown, external file:

RST .. rcsv-table:: Title :file: table.mcsv

Markdown, inline data.

``RST .. rcsv-table:: Title

Col 1, Row 1
Col 2, Row 2

``

Merging Cells

Columns

``RST .. rcsv-table:: Title

Merged,<
Unmerged, Unmerged

``

Rows

``RST .. rcsv-table:: Title

Merged,Unmerged
^, Unmerged

``

Options

Supported options include:

• :file: Path to the .rcsv or .mcsv file.
• :header-rows: Number of top rows to format as header rows. If :sticky-header: is set, these rows become sticky.
• :width: CSS width for the table, such as 100%.
• :widths: A space-separated list of column widths.
• :class: Additional classes to add to the table.
• :text-align: Horizontal alignment of text in the cells. Default is left.
• :vertical-align: Vertical alignment of text in cells. Default is middle.
• :sticky-header: Make the header rows sticky when scrolling long tables.
• :sticky-offset: CSS offset for sticky headers, such as 3.5rem.
• :strict: Treat ragged rows and malformed input as errors instead of warnings.
• :sortable: Enable row sorting by clicking on the headers.
• :search: Add a search field with a row count to the table and enable searching.
• :sort-types: Assigns explicit sort types using COLUMN=TYPE entries.

Formatting

• Custom theming.
• =ALIGN() horizontal/vertical cell value alignment.
• =BG() set the background cell color.
• =FG() set text color.
• =ICON() use a Font Awesome or Bootstrap icon, or a fallback.
• =STATUS() insert a colored status pill.

Spreadsheet

• ' interprest as literal text without evaluation.
• +,-,*,/ arithmetic operations on cells.
• =C4 cell references.
• =A4:B4 cell ranges.
• =AVG() take the average.
• =CONCAT() concatenation of cell values.
• =COUNT() count number of numerical values.
• =IF() conditional evaluation.
• =MAX() find the maximum value.
• =MIN() find the minimum value.
• =ROUND() round the number to an int or the specified decimal places.
• =SUM() sum a set or range of values.