Convert Textile to RST

Why Convert Textile to RST?

Converting Textile to reStructuredText (RST) is essential when migrating documentation from Redmine or Textile-based platforms to Python documentation systems like Sphinx and Read the Docs. RST is the standard markup language for Python project documentation and offers powerful features for creating comprehensive, cross-referenced, multi-format documentation.

Textile and RST share the goal of being human-readable markup languages, but RST offers significantly more capabilities for technical documentation. RST's directive system allows embedding code blocks with syntax highlighting, admonitions (warnings, notes, tips), mathematical formulas, and auto-generated API documentation. These features make RST the preferred choice for software documentation projects.

Sphinx, the documentation generator built on RST, can produce HTML, PDF, EPUB, and man pages from the same source files. Combined with Read the Docs for automated building and hosting, RST provides a complete documentation pipeline that Textile cannot match. Converting your Textile content to RST opens the door to this powerful ecosystem.

The syntax mapping between Textile and RST is straightforward: Textile headings (h1., h2.) become RST underlined headings, bold and italic markers are translated, and lists are reformatted. Tables require restructuring from Textile's pipe syntax to RST's grid or simple table format, which our converter handles automatically.

Key Benefits of Converting Textile to RST:

• Sphinx Integration: Use RST with Sphinx for professional documentation sites
• Read the Docs: Host documentation on Read the Docs platform
• Cross-References: Link between documents, sections, and API elements
• Multi-Format Output: Generate HTML, PDF, EPUB from single source
• Python Standard: Standard format for Python package documentation
• Directives: Access code highlighting, admonitions, and more
• Extensibility: Create custom directives and roles

Practical Examples

Example 1: Project Documentation

Input Textile file (readme.textile):

h1. MyProject Documentation

h2. Installation

Install the package using pip:

bc. pip install myproject

h2. Quick Start

* Import the module
* Create a configuration file
* Run the application

h2. Features

|_. Feature     |_. Status    |
| REST API      | Stable      |
| WebSocket     | Beta        |
| GraphQL       | Planned     |

Output RST file (readme.rst):

MyProject Documentation
=======================

Installation
------------

Install the package using pip:

.. code-block:: bash

    pip install myproject

Quick Start
-----------

* Import the module
* Create a configuration file
* Run the application

Features
--------

=========  ========
Feature    Status
=========  ========
REST API   Stable
WebSocket  Beta
GraphQL    Planned
=========  ========

Example 2: API Documentation

Input Textile file (api.textile):

h1. API Reference

h2. Authentication

All endpoints require an *API key* passed in the header.

h3. GET /api/users

Returns a list of all users.

bq. Note: Results are paginated with 50 items per page.

h3. POST /api/users

Creates a new user. Required fields:

# username (string)
# email (string)
# role (string, optional)

Output RST file (api.rst):

API Reference
=============

Authentication
--------------

All endpoints require an **API key** passed in the header.

GET /api/users
~~~~~~~~~~~~~~

Returns a list of all users.

.. note::

    Results are paginated with 50 items per page.

POST /api/users
~~~~~~~~~~~~~~~

Creates a new user. Required fields:

#. username (string)
#. email (string)
#. role (string, optional)

Example 3: Migration from Redmine Wiki

Input Textile file (wiki.textile):

h1. Development Guide

h2. Prerequisites

* Python 3.8+
* PostgreSQL 13+
* Redis 6+

h2. Setup

_Clone the repository:_

bc. git clone https://github.com/example/project.git
cd project
pip install -r requirements.txt

h2. Running Tests

bc. pytest tests/ -v

Output RST file (wiki.rst):

Development Guide
=================

Prerequisites
-------------

* Python 3.8+
* PostgreSQL 13+
* Redis 6+

Setup
-----

*Clone the repository:*

.. code-block:: bash

    git clone https://github.com/example/project.git
    cd project
    pip install -r requirements.txt

Running Tests
-------------

.. code-block:: bash

    pytest tests/ -v

Frequently Asked Questions (FAQ)

Q: What is reStructuredText (RST)?

A: reStructuredText (RST) is a plain-text markup language developed as part of the Python Docutils project. It is the standard markup for Python documentation, used by Sphinx (the documentation generator) and hosted on Read the Docs. RST offers powerful features like directives, cross-references, and multi-format output that make it ideal for technical documentation projects.

Q: How are Textile headings converted to RST?

A: Textile headings like h1., h2., h3. are converted to RST underline-style headings. RST uses different underline characters to denote heading levels: = for h1, - for h2, ~ for h3, ^ for h4, and so on. The heading text is placed on one line with the underline character repeated on the next line to match the text length.

Q: Can I use the converted RST with Sphinx?

A: Yes! The converted RST files are fully compatible with Sphinx. You can add them to a Sphinx documentation project, include them in the table of contents (toctree), and build HTML, PDF, or EPUB output. You may want to add Sphinx-specific directives (like toctree, automodule) after conversion for enhanced functionality.

Q: Are Textile tables converted properly to RST?

A: Yes, Textile tables are converted to RST simple table format. RST supports two table styles: grid tables (using +, -, |) and simple tables (using = and spaces). The converter produces clean, properly formatted RST tables with correct column alignment and header separation.

Q: What happens to Textile code blocks?

A: Textile code blocks (bc. prefix) are converted to RST code-block directives (.. code-block::). The RST format supports syntax highlighting for many languages, so you can specify the language after conversion for enhanced code display in the generated documentation.

Q: Is RST better than Markdown for documentation?

A: RST excels at large, structured documentation projects thanks to its directive system, cross-referencing, and Sphinx integration. Markdown is simpler and more widely adopted for general content. For Python projects and technical documentation requiring API docs, cross-references, and multi-format output, RST with Sphinx is the superior choice.

Q: Can I host the converted documentation on Read the Docs?

A: Yes! Read the Docs natively supports RST files with Sphinx. After converting your Textile content to RST, set up a Sphinx project with a conf.py file, push to GitHub/GitLab, and connect to Read the Docs for automatic building and hosting of your documentation.

Q: How do Textile links convert to RST format?

A: Textile inline links ("Link text":http://example.com) are converted to RST inline links (`Link text <http://example.com>`_). RST also supports reference-style links and named hyperlink targets, which can be manually added after conversion for cleaner document structure.