sphinx-tabular

sphinx-tabular#

PyPI link Python link Docs link PyPI total downloads

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, background color, text color, and alignment) is HTML only.

Features#

  • Sphinx extension.

  • Uses standard CSV files or native reStructuredText list-table syntax.

  • Easily merge table cells with < and ^.

  • Support reStructuredText and Markdown.

Three table directives.#
.. rcsv-table::
.. mcsv-table::
.. rlist-table::

  • 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 tables.

Dependencies#

  • python3 > 3.11

  • sphinx >= 7

  • docutils >= 0.20

  • myst-parser >= 5

Installation#

Install from the Python Package Index.

pip install sphinx-tabular

Enable the extension in conf.py:

extensions = [
    "sphinx_tabular",
]

The extension also loads myst_parser so that mcsv-table cells can be parsed as MyST Markdown.

Directives#

sphinx-tabular provides three directives.

  • .. rcsv-table:: for CSV rows with reStructuredText cell content.

  • .. mcsv-table:: for CSV rows with Markdown cell content.

  • .. rlist-table:: for a two-level reStructuredText bullet list with rich cell content.

rcsv-table for reStructuredText#

Use rcsv-table for CSV tables whose cells contain reStructuredText.

Inline#
.. rcsv-table:: Interface Matrix
    :header-rows: 1
    :width: 100%

    A,B,C
    D,E,=STATUS(F; green)
External file.#
.. rcsv-table:: Interface Matrix
    :file: table.rcsv
    :header-rows: 1
    :width: 100%

mcsv-table for Markdown#

Use mcsv-table for CSV tables whose cells contain MyST Markdown.

Inline#
.. mcsv-table:: Markdown Matrix
    :header-rows: 1
    :width: 100%

    A,B,C
    D,E,=STATUS(F; green)
External file.#
.. mcsv-table:: Markdown Matrix
    :file: table.mcsv
    :header-rows: 1
    :width: 100%

rlist-table for rich reStructuredText#

Use rlist-table when cells need normal reStructuredText block content without CSV quoting. Each top-level list item is a row, and each nested list item is a cell.

Inline list table#
.. rlist-table:: Interface Matrix
    :header-rows: 1
    :stub-columns: 1

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

See rlist-table for list structure, literal marker escaping, rich cell content, formulas, and interactive options.

Options#

Supported options include:

  • :align: Place the table at left, center, or right. Supported by rlist-table.

  • :class: Additional classes to add to the table.

  • :file: Path to the .rcsv or .mcsv file. This option is 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. Supported by 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 explicit interactive sort types using one-based COLUMN=TYPE entries.

  • :sticky-header: Make the header row or 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 stub columns. Supported by rlist-table.

  • :text-align: Horizontal alignment of text in the cells. Default is left.

  • :width: CSS width for the table, such as 100%.

  • :widths: A space-separated list of column widths.

  • :vertical-align: Vertical alignment of text in cells. Default is middle.

Known Limitations#

  • sphinx-tabular is intended for documentation tables, not as a full spreadsheet engine.

  • Formula support is intentionally small. The extension currently supports cell references, STATUS(), ICON(), ALIGN(), HALIGN(), VALIGN(), and pipe modifiers. Arithmetic expressions support basic +, -, *, and / operations. Advanced spreadsheet-style math functions and complex expression parsing are not currently supported.

  • Formula arguments use semicolons (;) instead of commas. This is intentional so formulas can be written naturally inside comma-separated table rows without extra quoting.

  • Merge markers are fixed. In CSV directives, an unquoted < or ^ is a marker and a quoted marker is literal. In rlist-table, a plain-text marker is active and an inline literal such as ``<`` or ``^`` is displayed literally. These markers are not currently configurable.

  • Complex or invalid merge layouts may produce warnings or unexpected output. The extension is designed for simple horizontal and vertical merges, not arbitrary spreadsheet-like merge regions.

  • .rcsv cells are parsed as reStructuredText, .mcsv cells are parsed with MyST Markdown, and rlist-table cells retain parsed reStructuredText nodes. Mixing markup syntaxes in the same table is not supported.

  • .mcsv support requires myst-parser. The extension loads it automatically, but projects should still include myst-parser as an installed dependency.

  • ICON() emits CSS classes only. Full Font Awesome or Bootstrap Icons support requires the project to load those icon styles and fonts locally. sphinx-tabular includes fallback glyphs for a small set of common icons, but it does not bundle full icon font libraries.

  • Sticky headers use a small JavaScript helper to support multi-row headers. If JavaScript is disabled, tables still render normally, but multi-row sticky header offsets may not work.

  • Sticky headers may require theme-specific CSS adjustments in heavily customized Sphinx themes, especially themes that apply unusual table wrappers, overflow rules, or custom table border behavior.

  • Tables are normalized to the longest row. Shorter rows are padded with empty cells. In non-strict mode this produces warnings; in strict mode it raises an error.

  • The extension does not currently provide an interactive editor. Tables are authored as inline directive content, native rlist-table lists, or external .rcsv / .mcsv files.

  • The extension does not bundle DataTables, filtering, pagination, or other interactive table libraries. Additional classes such as datatables are passed through so projects can integrate their own local JavaScript if needed.

  • IF() numeric comparisons support simple numeric values only. Full arithmetic expressions such as A2 + B2 > 10 are not currently supported.

  • Range references are supported. SUM() is implemented, but AVG(), MIN(), and MAX() are not currently implemented.

  • Arithmetic expressions are numeric-only. Non-numeric operands return #VALUE! and produce a warning.

  • BG() and FG() intentionally support a limited set of safe CSS color formats: named colors, hex colors, and simple CSS custom properties such as var(--pst-color-primary).

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

Changelog#

0.2.4#

  • Added rlist-table for uniform two-level reStructuredText lists.

  • Added rich parsed reStructuredText cell content for list tables.

  • Added :stub-columns:, :align:, and :name: support to rlist-table.

  • Added merge markers, formulas, sticky headers, sorting, initial sorting, and searching to list tables.

0.2.3#

  • Fixed header row spacing with sort button.

  • Added :search: option.

  • Added hybrid sort.

    • Default sort is auto, which uses header text and rendered values to determine sort type.

    • Optional :sort-types: when automatic detection is not appropriate.

0.2.2#

  • Added :sortable: option to sort rows by clicking on the header row. Supports merged header rows.

0.1.0#

Initial release.

Features:

  • rcsv-table directive for reStructuredText cell content.

  • mcsv-table directive for MyST Markdown cell content.

  • External and inline CSV table support.

  • Horizontal and vertical merge markers.

  • Formula support.

  • Alignment, status, icons, background color, and text color helpers.