Convert RST to TOML

Why Convert RST to TOML?

Converting reStructuredText (RST) documents to TOML format is useful when you need to extract structured configuration data from documentation files. While RST is designed for documentation, TOML excels at storing configuration settings in a human-readable format.

TOML has become the standard configuration format in the Python ecosystem through pyproject.toml (PEP 518). If you have configuration documentation in RST format that describes project settings, dependencies, or build configurations, converting to TOML allows you to use that information directly in your project setup.

This conversion is particularly valuable when documenting configuration options. Rather than maintaining separate documentation and configuration files, you can write your settings in RST (with all its documentation features) and then convert to TOML for actual use in your project.

TOML's clear syntax and support for native data types (strings, integers, floats, booleans, datetimes, arrays) make it ideal for configuration files. The conversion extracts structured data from RST field lists, tables, and definition lists into proper TOML sections and key-value pairs.

Key Benefits of Converting RST to TOML:

• Configuration Extraction: Pull settings from documentation into usable config files
• Python Packaging: Generate pyproject.toml content from documented specifications
• Type Safety: TOML's strong typing vs RST's text-only approach
• Build Systems: Create configuration for Cargo, Hugo, and other TOML-based tools
• Clarity: Unambiguous key-value syntax that's easy to parse
• Standardization: Industry-standard format for project configuration
• Validation: TOML parsers provide syntax validation

Practical Examples

Example 1: Project Configuration

Input RST file (config.rst):

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

Metadata
--------

:name: my-awesome-project
:version: 2.1.0
:description: A sample Python project
:author: John Developer

Build Settings
--------------

:python_version: 3.10
:build_backend: setuptools

Output TOML file (config.toml):

# Project Configuration

[metadata]
name = "my-awesome-project"
version = "2.1.0"
description = "A sample Python project"
author = "John Developer"

[build-settings]
python_version = "3.10"
build_backend = "setuptools"

Example 2: Dependencies List

Input RST file (dependencies.rst):

Dependencies
============

Required
--------

* requests >= 2.28.0
* click >= 8.0
* pydantic >= 2.0

Development
-----------

* pytest >= 7.0
* black >= 23.0
* mypy >= 1.0

Output TOML file (dependencies.toml):

# Dependencies

[dependencies]
requests = ">=2.28.0"
click = ">=8.0"
pydantic = ">=2.0"

[dev-dependencies]
pytest = ">=7.0"
black = ">=23.0"
mypy = ">=1.0"

Example 3: Application Settings

Input RST file (settings.rst):

Application Settings
====================

Database
--------

+----------+----------------------+
| Setting  | Value                |
+==========+======================+
| host     | localhost            |
+----------+----------------------+
| port     | 5432                 |
+----------+----------------------+
| name     | myapp_db             |
+----------+----------------------+

Server
------

:host: 0.0.0.0
:port: 8000
:debug: true
:workers: 4

Output TOML file (settings.toml):

# Application Settings

[database]
host = "localhost"
port = 5432
name = "myapp_db"

[server]
host = "0.0.0.0"
port = 8000
debug = true
workers = 4

Frequently Asked Questions (FAQ)

Q: What is TOML?

A: TOML (Tom's Obvious Minimal Language) is a configuration file format designed to be easy to read due to its clear semantics. Created by Tom Preston-Werner (GitHub co-founder) in 2013, it's now widely used for Python projects (pyproject.toml) and Rust projects (Cargo.toml).

Q: Why use TOML instead of JSON or YAML?

A: TOML is more readable than JSON (allows comments, no excessive braces) and less error-prone than YAML (no indentation issues, clear typing). It's specifically designed for configuration files, making it ideal for project settings and metadata.

Q: What RST elements convert best to TOML?

A: Field lists (:key: value), definition lists, and simple tables convert well to TOML key-value pairs and sections. Headers become TOML table names. Prose text and complex formatting like code blocks don't have direct TOML equivalents since TOML is for data, not documents.

Q: Can I use this for pyproject.toml?

A: Yes! If you document your project configuration in RST format (common in Python projects), you can convert it to TOML and use the output as a starting point for your pyproject.toml. You may need to adjust the structure to match PEP 621 requirements.

Q: How are data types handled in conversion?

A: The converter attempts to infer types: numbers become integers or floats, "true"/"false" become booleans, dates are parsed when possible, and everything else becomes strings. You may need to manually adjust types in the output for complex cases.

Q: Does Python have built-in TOML support?

A: Yes! Python 3.11+ includes tomllib in the standard library for reading TOML files. For writing TOML or for earlier Python versions, use the tomli (reading) and tomli-w (writing) packages, or toml for both operations.

Q: What tools validate TOML files?

A: Most TOML parsers validate syntax when loading files. Online validators like toml-lint are available. IDE plugins for VS Code, PyCharm, and others provide real-time validation. The taplo tool offers formatting and validation for TOML files.

Q: Can I convert TOML back to RST?

A: While there's no standard tool for this, you can write a script that reads TOML data and generates RST documentation. This is useful for generating documentation from configuration files automatically.