sphinx-tabular 0.2.4

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 files or native reStructuredText list-table syntax.
• Easily merge table cells with < and ^.
• Support reStructuredText, rich reStructuredText list cells, 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

extensions = [
    ...,
    "sphinx_tabular",
    ...,
]

Directives

rcsv-table

Use CSV rows with reStructuredText cell content. Data may be inline or loaded from an external .rcsv file.

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

mcsv-table

Use CSV rows with MyST Markdown cell content. Data may be inline or loaded from an external .mcsv file.

.. mcsv-table:: Title
    :file: table.mcsv

rlist-table

Use a uniform two-level reStructuredText bullet list. Each top-level item is a row, and each nested item is a cell. Rich reStructuredText nodes are preserved inside ordinary cells.

.. rlist-table:: Interface status
    :header-rows: 1
    :stub-columns: 1

    * - Name
      - Owner
      - Status
    * - Alpha
      - **Able Team**
      - =STATUS(Ready; green)

rlist-table is inline-only. Use .. include:: when the list should be kept in another source file.

Merging Cells

In rcsv-table and mcsv-table, an unquoted < merges with the cell to its left and an unquoted ^ merges with the cell above it.

.. rcsv-table:: Horizontal merge

    Merged,<
    Unmerged,Unmerged

.. rcsv-table:: Vertical merge

    Merged,Unmerged
    ^,Unmerged

In rlist-table, a cell containing one plain-text < or ^ is a merge marker. Use an inline literal such as `<` or `^` when the character should be displayed instead.

.. rlist-table:: List merge

    * - Merged
      - <
    * - Unmerged
      - Unmerged

Options

Supported options include:

• :align: Place an rlist-table at left, center, or right.
• :class: Additional classes to add to the table.
• :file: Path to the .rcsv or .mcsv file. Not supported by rlist-table.
• :header-rows: Number of top rows to format as header rows. If :sticky-header: is set, these rows become sticky.
• :initial-sort: Apply independent page-load ordering using one-based COLUMN=TYPE[:reverse] criteria.
• :name: Assign an explicit target name to an rlist-table.
• :search: Add a search field with a row count to the table and enable searching.
• :sortable: Enable row sorting by clicking on the headers.
• :sort-types: Assign interactive sort types using one-based COLUMN=TYPE entries.
• :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.
• :stub-columns: Mark leftmost columns as semantic stubs for rlist-table.
• :text-align: Horizontal alignment of text in the cells. Default is left.
• :vertical-align: Vertical alignment of text in cells. Default is middle.
• :width: CSS width for the table, such as 100%.
• :widths: A space-separated list of column widths.

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.