Convert TOML to RST

Why Convert TOML to RST?

Converting TOML files to reStructuredText is valuable when you need to generate human-readable documentation from configuration data. Configuration files often contain critical project metadata, dependency lists, and settings that should be documented alongside your codebase. By converting TOML to RST, you can seamlessly integrate configuration documentation into Sphinx-based documentation projects without manual transcription.

TOML's structured tables and typed values translate well into RST's rich document markup. Table sections become RST headings, key-value pairs become definition lists or formatted tables, and arrays become bulleted lists. The resulting RST document provides a clear, readable representation of your configuration that can be included in your Sphinx documentation, rendered to HTML, PDF, or ePub, and kept in sync with the actual configuration file through automated conversion.

This conversion is particularly useful for Python projects that use pyproject.toml. The project metadata, build requirements, tool configurations, and dependency specifications stored in pyproject.toml can be automatically documented in RST format for inclusion in ReadTheDocs or similar documentation hosting platforms. This eliminates the common problem of configuration documentation falling out of sync with actual settings.

reStructuredText's directive system also allows the converted content to be enhanced with additional formatting, cross-references, and semantic markup that TOML cannot express. Once converted, you can add notes, warnings, code examples, and hyperlinks to create comprehensive documentation that goes beyond a simple configuration reference.

Key Benefits of Converting TOML to RST:

• Documentation Integration: Include config data in Sphinx projects
• ReadTheDocs Ready: Publish configuration docs online
• Multi-Format Output: Generate HTML, PDF, ePub from RST
• Automated Sync: Keep docs updated with config changes
• Rich Formatting: Tables, code blocks, and cross-references
• Python Ecosystem: Native format for Python documentation
• Structured Content: Section hierarchy from TOML tables

Practical Examples

Example 1: Python Project Configuration Documentation

Input TOML file (pyproject.toml):

[project]
name = "data-pipeline"
version = "3.1.0"
description = "ETL pipeline for data warehousing"
requires-python = ">=3.10"

[project.dependencies]
pandas = ">=2.0"
sqlalchemy = ">=2.0"
apache-airflow = ">=2.8"

Output RST file (project-config.rst):

Project Configuration
=====================

Project
-------

- **name**: data-pipeline
- **version**: 3.1.0
- **description**: ETL pipeline for data warehousing
- **requires-python**: >=3.10

Dependencies
------------

.. list-table::
   :header-rows: 1

   * - Package
     - Version
   * - pandas
     - >=2.0
   * - sqlalchemy
     - >=2.0
   * - apache-airflow
     - >=2.8

Example 2: Cargo Project Documentation

Input TOML file (Cargo.toml):

[package]
name = "web-server"
version = "0.5.2"
edition = "2021"
authors = ["Jane Developer "]

[dependencies]
tokio = { version = "1.35", features = ["full"] }
axum = "0.7"
serde = { version = "1.0", features = ["derive"] }

Output RST file (cargo-config.rst):

Cargo Configuration
===================

Package
-------

:name: web-server
:version: 0.5.2
:edition: 2021
:authors: Jane Developer <[email protected]>

Dependencies
------------

**tokio** ``1.35``
   Features: full

**axum** ``0.7``

**serde** ``1.0``
   Features: derive

Example 3: Application Settings Reference

Input TOML file (settings.toml):

[cache]
backend = "redis"
ttl = 3600
max_entries = 10000

[cache.redis]
host = "127.0.0.1"
port = 6379
db = 0

[logging]
level = "INFO"
format = "%(asctime)s - %(name)s - %(levelname)s"

Output RST file (settings-ref.rst):

Application Settings Reference
==============================

Cache
-----

+---------------+----------+----------------------------+
| Key           | Type     | Value                      |
+===============+==========+============================+
| backend       | string   | redis                      |
+---------------+----------+----------------------------+
| ttl           | integer  | 3600                       |
+---------------+----------+----------------------------+
| max_entries   | integer  | 10000                      |
+---------------+----------+----------------------------+

Cache > Redis
~~~~~~~~~~~~~

- **host**: ``127.0.0.1``
- **port**: ``6379``
- **db**: ``0``

Logging
-------

- **level**: ``INFO``
- **format**: ``%(asctime)s - %(name)s - %(levelname)s``

Frequently Asked Questions (FAQ)

Q: How are TOML tables mapped to RST structure?

A: TOML tables ([section]) become RST section headings with appropriate underline characters. Nested tables create subsection hierarchies. Key-value pairs within tables are rendered as definition lists, field lists, or formatted tables depending on the content structure.

Q: Can I include the converted RST in my Sphinx documentation?

A: Yes, the output is valid RST that can be directly included in any Sphinx project using the .. include:: directive or by placing the file in your documentation source directory. It follows standard RST conventions and renders correctly with Sphinx.

Q: Are TOML data types preserved in the RST output?

A: RST is a documentation format without a type system, so TOML types become formatted text. However, type information can be indicated through formatting conventions -- for example, strings in quotes, numbers as-is, and booleans as true/false. Code formatting (backticks) is used for values to distinguish them from prose.

Q: How are TOML arrays represented in RST?

A: TOML arrays are converted to RST bullet lists. Arrays of tables become subsections with repeated structure. Inline arrays may be rendered as comma-separated items within a list entry, depending on complexity.

Q: Can I convert pyproject.toml to RST for ReadTheDocs?

A: Absolutely. This is one of the most common use cases. The project metadata, dependencies, and tool configurations from pyproject.toml translate cleanly into RST documentation that ReadTheDocs can build and host automatically.

Q: Will the RST output include a table of contents?

A: The converter generates properly structured RST sections that Sphinx can automatically include in a table of contents via the .. toctree:: directive. You can also add a .. contents:: directive to the converted file for a local table of contents.

Q: How does the converter handle multi-line TOML strings?

A: Multi-line TOML strings (both basic """ and literal ''') are converted to RST literal blocks or block quotes, preserving the original content and line breaks. This is particularly useful for documenting configuration values that contain long text.

Q: Can I customize the RST output format?

A: The converter produces standard RST that you can freely edit after conversion. You can add Sphinx directives, cross-references, admonitions (notes, warnings), and any other RST markup to enhance the documentation beyond what the TOML data provides.