Convert XLSX to RST

Why Convert XLSX to reStructuredText?

Converting XLSX Excel files to reStructuredText format transforms structured spreadsheet data into beautifully aligned grid tables that are perfect for Sphinx-based documentation. While Excel is great for data analysis, RST grid tables display data in a visually structured way that is readable both as plain text and when rendered to HTML or PDF through Sphinx.

RST grid tables use ASCII art characters (+, -, |, =) to create visually distinct borders around each cell. The header row is separated by equals signs (=) instead of hyphens, making it immediately distinguishable. Our converter reads the Excel workbook, extracts data from the active worksheet, detects header rows, and calculates the optimal column widths to produce properly aligned RST grid tables.

This conversion is especially valuable for Python developers and technical writers who use Sphinx for documentation. Instead of manually constructing grid tables character by character, you can export data from Excel, convert it to RST, and paste it directly into your .rst documentation files. The result renders beautifully in Sphinx-generated HTML, PDF, and EPUB outputs.

XLSX to RST conversion is also useful for creating specification tables, configuration references, API parameter lists, and changelog tables in Python project documentation. The converter ensures proper column alignment and handles special characters in cell values, producing valid RST markup that Docutils and Sphinx can process without errors.

Key Benefits of Converting XLSX to RST:

• Grid Tables: Produces properly aligned RST grid tables with ASCII borders
• Header Recognition: First row is formatted as the table header with = separators
• Column Alignment: Automatically calculates optimal column widths for perfect alignment
• Sphinx Compatible: Output integrates directly into Sphinx documentation projects
• Multi-Format Output: RST tables render to HTML, PDF, EPUB, and LaTeX through Sphinx
• Formula Results: Excel calculations are exported as their computed values
• Version Control: RST is plain text, ideal for Git repositories

Practical Examples

Example 1: API Parameter Reference

Input XLSX file (api_params.xlsx):

| Parameter | Type   | Required | Description                |
|-----------|--------|----------|----------------------------|
| api_key   | string | Yes      | Your API authentication key|
| format    | string | No       | Response format (json/xml) |
| limit     | int    | No       | Max results (default: 100) |
| offset    | int    | No       | Pagination offset          |

Output RST file (api_params.rst):

+-----------+--------+----------+----------------------------+
| Parameter | Type   | Required | Description                |
+===========+========+==========+============================+
| api_key   | string | Yes      | Your API authentication key|
+-----------+--------+----------+----------------------------+
| format    | string | No       | Response format (json/xml) |
+-----------+--------+----------+----------------------------+
| limit     | int    | No       | Max results (default: 100) |
+-----------+--------+----------+----------------------------+
| offset    | int    | No       | Pagination offset          |
+-----------+--------+----------+----------------------------+

Example 2: Python Package Dependencies

Input XLSX file (dependencies.xlsx):

| Package  | Version | License    | Purpose       |
|----------|---------|------------|---------------|
| Django   | 4.2     | BSD        | Web framework |
| requests | 2.31    | Apache 2.0 | HTTP client   |
| celery   | 5.3     | BSD        | Task queue    |
| redis    | 5.0     | MIT        | Cache backend |

Output RST file (dependencies.rst):

+----------+---------+------------+---------------+
| Package  | Version | License    | Purpose       |
+==========+=========+============+===============+
| Django   | 4.2     | BSD        | Web framework |
+----------+---------+------------+---------------+
| requests | 2.31    | Apache 2.0 | HTTP client   |
+----------+---------+------------+---------------+
| celery   | 5.3     | BSD        | Task queue    |
+----------+---------+------------+---------------+
| redis    | 5.0     | MIT        | Cache backend |
+----------+---------+------------+---------------+

Example 3: Configuration Options

Input XLSX file (config.xlsx):

| Option      | Type   | Default | Description              |
|-------------|--------|---------|--------------------------|
| timeout     | int    | 30      | Connection timeout (sec) |
| max_retries | int    | 3       | Maximum retry attempts   |
| debug       | bool   | false   | Enable debug logging     |
| log_level   | string | INFO    | Logging verbosity level  |

Output RST file (config.rst):

+-------------+--------+---------+--------------------------+
| Option      | Type   | Default | Description              |
+=============+========+=========+==========================+
| timeout     | int    | 30      | Connection timeout (sec) |
+-------------+--------+---------+--------------------------+
| max_retries | int    | 3       | Maximum retry attempts   |
+-------------+--------+---------+--------------------------+
| debug       | bool   | false   | Enable debug logging     |
+-------------+--------+---------+--------------------------+
| log_level   | string | INFO    | Logging verbosity level  |
+-------------+--------+---------+--------------------------+

Frequently Asked Questions (FAQ)

Q: What is reStructuredText (RST) format?

A: reStructuredText (RST) is a lightweight markup language originally created for Python documentation. It is processed by Docutils and Sphinx to produce HTML, PDF, EPUB, and other output formats. RST supports two table styles: grid tables (using ASCII borders) and simple tables. Grid tables are the most common and offer full support for cell spanning and complex layouts. RST is the standard documentation format for Python projects hosted on Read the Docs.

Q: How are column widths determined in the grid table?

A: The converter scans all values in each column (including headers) and uses the maximum width as the column width. Each cell is then padded with spaces to align perfectly within the grid. This ensures the table is visually correct and renders properly in Sphinx. You can manually adjust column widths in the output if needed.

Q: Will Excel column headers appear in the RST table?

A: Yes! The converter detects the header row and separates it from data rows using equals signs (=====) instead of hyphens. This is the standard RST convention for distinguishing header rows. The headers appear in the first row of the grid table and are rendered with bold formatting in Sphinx output.

Q: Are Excel formulas preserved?

A: Excel formulas are evaluated and their computed results appear in the RST grid table as plain text values. RST does not support formulas or calculations. For example, if a cell contains =AVERAGE(B2:B10) and the result is 85.3, the RST output will contain the value 85.3.

Q: Can I use the output directly in Sphinx documentation?

A: Absolutely! The generated RST grid table follows standard Docutils/Sphinx syntax and can be pasted directly into any .rst file. You can also use the RST include directive to reference the converted file from your main document. The table will render correctly when built with Sphinx, producing properly formatted HTML and PDF output.

Q: What happens with multiple worksheets?

A: By default, the converter processes the first (active) worksheet. If your workbook contains multiple sheets, only the active sheet is converted to an RST grid table. You can convert other sheets separately or ensure the desired sheet is active before uploading.

Q: What about special characters in Excel cells?

A: Special characters like pipes (|), plus signs (+), and hyphens (-), which are significant in RST grid table syntax, are preserved in cell values. The converter ensures proper cell padding so these characters do not interfere with the table structure. UTF-8 characters from Excel cells are fully supported.

Q: Is there a limit on columns or rows?

A: There is no hard limit, but RST grid tables with very wide columns or many columns may wrap awkwardly in text editors. For documentation purposes, tables with up to 6-8 columns and a reasonable number of rows work best. For very large datasets, consider JSON, CSV, or XLSX format instead of RST grid tables.