What is reStructuredText?
reStructuredText (RST) is the standard lightweight markup language used for Python documentation. It is the format of choice for Sphinx, the documentation tool behind the official Python docs, NumPy, Django, Flask, and thousands of other projects. RST supports rich tables, cross-references, code blocks, directives, and section headers — making it ideal for technical documentation.
This tool converts your JSON data into RST-formatted tables or field lists, ready to paste directly into your .rst source files.
RST Table Formats
This converter supports three RST table formats:
- Grid Table — Uses
+, -, and | characters to draw explicit cell borders. Widest compatibility; renders correctly in all RST processors. Best for documentation that may be rendered in multiple tools.
- List Table — Uses the
.. list-table:: directive with bullet-list syntax. Easier to edit by hand and does not require precise column width alignment. Recommended for tables that will be frequently updated.
- Simple Table — Uses
= lines for column separators. Compact and human-readable but limited (no row spans, requires aligned columns). Good for simple lookup tables.
How to Use This Tool
- Paste a JSON array of objects (each object becomes a table row, keys become column headers) or a single JSON object (converted to a key/value field list).
- Select your preferred table format from the dropdown.
- Optionally add a table title — it will appear as an RST section heading above the table.
- Click "Convert to RST" to generate the output.
- Copy the RST and paste it into your
.rst file or Sphinx project.
Real-World Use Cases
Sphinx Documentation for Python Packages
When documenting Python packages with Sphinx, you often need to present configuration options, API parameters, or data models as tables. If your configuration schema is stored as JSON (for example, a config.schema.json file), convert the example JSON directly to an RST grid table and include it in your docs/ folder. This keeps documentation in sync with your schema without manual reformatting.
.. list-table:: Configuration Options
:header-rows: 1
:widths: auto
* - key
- type
- default
* - timeout
- integer
- 30
* - retries
- integer
- 3
API Response Documentation
REST API documentation often requires showing example response fields in a structured table. Paste a sample JSON response from your API, convert it to a field list or grid table, and embed it directly in your RST-based API docs. This is particularly useful for Sphinx-based documentation where Markdown is not the primary format.
Technical Writing and Release Notes
Many Python projects (including CPython itself) write release notes and changelogs in RST. If you have structured data about new features, deprecations, or bug fixes stored as JSON, converting it to an RST table is faster than hand-formatting each row. The list-table format is easiest to maintain for this purpose.
Frequently Asked Questions
Q: What is the difference between RST and Markdown?
A: Both are lightweight markup languages, but RST is more powerful and more complex. RST has a richer directive system (for notes, warnings, code blocks, include directives, etc.) and first-class table support. Markdown is simpler and more widely used for general documentation, but lacks RST's extensibility. The Python ecosystem strongly favors RST/Sphinx.
Q: Which table format should I use?
A: Use grid table for maximum compatibility and when the table will be rendered by multiple tools. Use list-table when you need to edit the table frequently (no column alignment required). Use simple table for small, compact lookup tables with short values.
Q: Can I use this output with MyST (Markdown for Sphinx)?
A: MyST-Parser allows using RST directives inside Markdown files, so the .. list-table:: output from this tool can be embedded in a .md file used with Sphinx + MyST. Grid and simple tables cannot be used directly in MyST Markdown — use the list-table format for cross-format compatibility.
Q: What happens if my JSON values contain pipe characters or special RST characters?
A: Pipe characters (|) in cell values can break grid and simple RST tables. The tool serializes all values to plain strings. For values with special characters, the list-table format is more robust because it uses indented bullet points rather than character-drawn borders.
Q: How do I include the RST table in a Sphinx project?
A: Copy the RST output and paste it directly into any .rst file in your Sphinx docs/ directory. Alternatively, save it as a separate file and use the .. include:: filename.rst directive in your main document. Run make html in your Sphinx project to build the HTML output.