Convert SQL to RST

Why Convert SQL to RST?

Converting SQL files to reStructuredText format is essential for creating professional database documentation. RST's powerful formatting capabilities, including tables, code blocks with syntax highlighting, and cross-referencing, make it ideal for documenting database schemas, query examples, and data dictionaries in a format that can be published as HTML, PDF, or ePub through Sphinx.

Database documentation is a critical but often neglected aspect of software development. By converting SQL schemas and queries to RST, teams can automatically generate comprehensive database reference documentation that stays synchronized with the actual database structure. RST's list-table directive perfectly represents SQL table schemas, while code-block directives preserve the original SQL syntax with highlighting.

The Sphinx documentation system, which uses RST as its primary format, offers powerful features for database documentation including automatic table of contents, cross-referencing between tables and their relationships, search functionality, and multi-format output. Converting SQL to RST enables integration of database documentation into existing Sphinx projects alongside API docs and user guides.

This conversion is particularly valuable for data engineering teams, database administrators, and organizations that maintain comprehensive technical documentation. The resulting RST files can be hosted on ReadTheDocs, integrated into CI/CD pipelines for automatic documentation updates, and versioned alongside the database migration scripts they document.

Key Benefits of Converting SQL to RST:

• Professional Documentation: Generate publication-quality database documentation
• Sphinx Integration: Seamless integration with Python documentation projects
• Multi-Format Output: Generate HTML, PDF, and ePub from a single source
• Cross-References: Link between tables, columns, and related documentation
• Code Highlighting: SQL syntax highlighting in documentation
• ReadTheDocs Ready: Host documentation online with automatic builds
• Version Control: Track documentation changes alongside schema changes

Practical Examples

Example 1: Schema Documentation

Input SQL file (schema.sql):

CREATE TABLE customers (
    id INT PRIMARY KEY AUTO_INCREMENT,
    name VARCHAR(100) NOT NULL,
    email VARCHAR(255) UNIQUE NOT NULL,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

CREATE INDEX idx_customers_email
    ON customers(email);

Output RST file (schema.rst):

Database Schema
===============

Customers Table
---------------

.. list-table:: customers
   :header-rows: 1
   :widths: 20 30 50

   * - Column
     - Type
     - Constraints
   * - id
     - INT
     - PRIMARY KEY AUTO_INCREMENT
   * - name
     - VARCHAR(100)
     - NOT NULL
   * - email
     - VARCHAR(255)
     - UNIQUE NOT NULL
   * - created_at
     - TIMESTAMP
     - DEFAULT CURRENT_TIMESTAMP

**Indexes:**

- ``idx_customers_email`` on ``email``

Example 2: Query Documentation

Input SQL file (reports.sql):

-- Monthly sales report
SELECT
    DATE_FORMAT(order_date, '%Y-%m') AS month,
    COUNT(*) AS total_orders,
    SUM(amount) AS total_revenue,
    AVG(amount) AS avg_order_value
FROM orders
WHERE order_date >= '2025-01-01'
GROUP BY DATE_FORMAT(order_date, '%Y-%m')
ORDER BY month DESC;

Output RST file (reports.rst):

Monthly Sales Report
====================

The following query generates a monthly sales summary
from the ``orders`` table.

.. code-block:: sql

   SELECT
       DATE_FORMAT(order_date, '%Y-%m') AS month,
       COUNT(*) AS total_orders,
       SUM(amount) AS total_revenue,
       AVG(amount) AS avg_order_value
   FROM orders
   WHERE order_date >= '2025-01-01'
   GROUP BY DATE_FORMAT(order_date, '%Y-%m')
   ORDER BY month DESC;

**Output columns:**

- ``month`` -- The year-month period
- ``total_orders`` -- Number of orders placed
- ``total_revenue`` -- Sum of all order amounts
- ``avg_order_value`` -- Average order amount

Example 3: Data Dictionary

Input SQL file (inventory.sql):

CREATE TABLE inventory (
    sku VARCHAR(20) PRIMARY KEY,
    product_name VARCHAR(200) NOT NULL,
    quantity INT DEFAULT 0,
    warehouse_id INT REFERENCES warehouses(id),
    last_restocked DATE
);

INSERT INTO inventory VALUES
('SKU-001', 'Widget A', 150, 1, '2025-12-01'),
('SKU-002', 'Gadget B', 75, 2, '2025-11-15');

Output RST file (inventory.rst):

Inventory Table
===============

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

   * - Column
     - Type
     - Description
   * - sku
     - VARCHAR(20)
     - Primary key, stock keeping unit
   * - product_name
     - VARCHAR(200)
     - Product display name (required)
   * - quantity
     - INT
     - Current stock level (default: 0)
   * - warehouse_id
     - INT
     - Foreign key to warehouses table
   * - last_restocked
     - DATE
     - Date of last inventory restock

.. note::

   The ``warehouse_id`` column references the
   ``warehouses`` table for location tracking.

Sample Data
-----------

.. csv-table::
   :header: SKU, Product, Qty, Warehouse, Restocked

   SKU-001, Widget A, 150, 1, 2025-12-01
   SKU-002, Gadget B, 75, 2, 2025-11-15

Frequently Asked Questions (FAQ)

Q: What is reStructuredText (RST)?

A: reStructuredText is a lightweight markup language used for technical documentation. It's the default format for Python project documentation and the Sphinx documentation generator. RST supports tables, code blocks, cross-references, directives, and can output to HTML, PDF, ePub, and other formats.

Q: How are SQL tables represented in RST?

A: SQL table definitions are converted to RST list-tables or grid tables, with columns for field name, data type, and constraints. Each SQL column becomes a row in the RST table. Indexes, foreign keys, and other constraints are documented as additional notes below the table.

Q: Can I use the RST output with Sphinx?

A: Yes! The generated RST files are fully compatible with Sphinx. You can include them in your Sphinx project's table of contents tree (toctree), and they'll be rendered as part of your documentation website. This makes it easy to integrate database documentation with existing project docs.

Q: Is SQL syntax preserved in the RST output?

A: Yes, original SQL statements are included in RST code-block directives with SQL syntax highlighting. This preserves the exact SQL syntax while also providing structured documentation tables. Readers can see both the formatted documentation and the original SQL code.

Q: How are SQL comments converted?

A: SQL comments (-- and /* */) are converted to RST prose text or note directives, depending on their position and content. Inline comments become descriptions within the documentation, while block comments may become section introductions or admonition blocks.

Q: Can I host the generated RST docs on ReadTheDocs?

A: Absolutely! ReadTheDocs natively supports Sphinx projects with RST files. After converting your SQL to RST, add the files to a Sphinx project, push to a Git repository, and connect it to ReadTheDocs for automatic building and hosting of your database documentation.

Q: What RST directives are used in the output?

A: The conversion uses several RST directives including list-table for schema definitions, code-block for SQL queries, csv-table for data records, note for important constraints, and warning for deprecation notices. These provide rich, semantic documentation structure.

Q: How are foreign key relationships documented?

A: Foreign key relationships are documented using RST cross-references and note directives. The referencing column is annotated with the target table and column, and when used within Sphinx, these can become clickable links to the referenced table's documentation page.