reStructuredText (RST) Tables for Technical Documentation

If you write documentation with Sphinx, contribute to Python projects, or maintain technical docs in plain text, you'll inevitably need to create tables in reStructuredText (RST). RST offers four distinct table formats, each suited to different use cases — from manually drawn grid tables to data-driven CSV directives.

This guide covers all four RST table types with practical examples, explains when to use each one, and shows how to convert existing data into RST format efficiently.

Why RST Tables Matter

reStructuredText is the default markup language for Python documentation (via Sphinx), and it's widely used in open-source projects, API documentation, and technical writing. Tables in RST serve critical roles:

• API reference documentation with parameter descriptions
• Configuration option tables
• Feature comparison matrices
• Changelog and version compatibility tables
• Data dictionaries and schema documentation

Grid Tables

Grid tables are the most visually explicit format — they look like the rendered table even in the source code. They use +, -, |, and = characters to draw cell borders:

+------------+----------+----------+
| Header 1   | Header 2 | Header 3 |
+============+==========+==========+
| Row 1      | Cell     | Cell     |
+------------+----------+----------+
| Row 2      | Cell     | Cell     |
+------------+----------+----------+
| Row 3      | Cell     | Cell     |
+------------+----------+----------+

Grid Table Rules

• The header separator uses = instead of -
• Every cell boundary must align perfectly
• Cells can span multiple lines of text (content wraps within the cell)
• Cells can span multiple columns or rows by removing internal borders

Column and Row Spanning in Grid Tables

+------------+----------+----------+
| Spanning   | Header 2 | Header 3 |
| Header     |          |          |
+============+==========+==========+
| Span 2 cols           | Cell     |
+------------+----------+----------+
| Cell       | Span 2 rows        |
+------------+                    +
| Cell       |                    |
+------------+----------+----------+

Pros: Visually clear, supports cell spanning, handles multi-line content.
Cons: Extremely tedious to create and maintain manually. Alignment must be pixel-perfect.

Simple Tables

Simple tables use a more concise syntax with = borders and spaces for column separation:

=====  =====  ======
Col 1  Col 2  Col 3
=====  =====  ======
A      B      C
D      E      F
G      H      I
=====  =====  ======

Simple Tables with Headers

========  ========  =========
Language  Paradigm  Year
========  ========  =========
Python    Multi     1991
Rust      Systems   2010
Go        Compiled  2009
========  ========  =========

Pros: Faster to type than grid tables, clean appearance in source.
Cons: Cannot span columns, limited to simple structures, column widths must align with content.

CSV-Table Directive

The csv-table directive is a game-changer for data-heavy documentation. Instead of manually drawing borders, you write comma-separated values and let the RST processor handle rendering:

.. csv-table:: Server Configuration
   :header: "Setting", "Default", "Description"
   :widths: 20, 15, 65

   "max_connections", "100", "Maximum concurrent connections"
   "timeout", "30s", "Request timeout duration"
   "log_level", "INFO", "Logging verbosity level"
   "cache_size", "256MB", "In-memory cache allocation"

CSV-Table Options

Loading External CSV Files

.. csv-table:: Sales Data 2025
   :file: data/quarterly_sales.csv
   :header-rows: 1
   :widths: auto

This approach is ideal for tables that are generated or updated frequently — edit the CSV, and the documentation updates automatically on the next build.

List-Table Directive

The list-table directive uses RST's native list syntax to define table data. Each bullet point represents a row, and nested bullets represent cells:

.. list-table:: HTTP Status Codes
   :header-rows: 1
   :widths: 15 25 60

   * - Code
     - Status
     - Description
   * - 200
     - OK
     - Request succeeded
   * - 301
     - Moved Permanently
     - Resource has been permanently moved
   * - 404
     - Not Found
     - Resource does not exist
   * - 500
     - Internal Server Error
     - Unexpected server-side error

Pros: Easy to write and maintain, no alignment issues, clear structure.
Cons: Can become verbose for tables with many columns.

Which Table Type Should You Use?

Sphinx Integration Tips

When using RST tables within Sphinx documentation, keep these tips in mind:

• Use the :widths: auto option in csv-table and list-table to let Sphinx calculate optimal column widths
• Apply table CSS classes with the :class: option for custom styling in your Sphinx theme
• Use tabularcolumns for LaTeX/PDF output to control column specifications
• Reference tables by adding a label before the directive and using :ref:
• Consider sphinx-datatables extension for interactive, sortable tables in HTML output

.. _config-table:

.. csv-table:: Configuration Reference
   :header: "Key", "Type", "Default"
   :class: longtable

   "debug", "boolean", "false"
   "port", "integer", "8080"

See :ref:`config-table` for configuration details.

Converting Data to RST Tables

Creating RST tables manually — especially grid tables — is one of the most time-consuming parts of writing technical documentation. Aligning columns, drawing borders, and maintaining consistency across edits is prone to errors.

ConvertMatrix streamlines this workflow. Use the CSV to reStructuredText converter to transform your spreadsheet data into properly formatted RST tables instantly. For Excel workbooks, the Excel to reStructuredText converter handles the conversion directly — no need to export to CSV first.

Conclusion

RST offers remarkable flexibility for tables in technical documentation. Grid tables provide visual clarity in source, simple tables offer quick formatting, csv-table connects your docs to data files, and list-table balances readability with maintainability. Choose the right type for your use case, and use tools like ConvertMatrix's CSV to RST and Excel to RST converters to eliminate the tedium of manual table formatting.