Convert Wiki to RST

Why Convert Wiki to RST?

Converting Wiki markup to reStructuredText (RST) is essential when migrating documentation from a wiki platform to a Sphinx-based documentation system. Many software projects start with wiki-based documentation for its ease of collaborative editing but eventually transition to RST and Sphinx for better version control integration, automated API documentation, and multi-format output. This conversion preserves your existing content structure while making it compatible with the Python documentation ecosystem.

RST provides significant advantages over wiki markup for technical documentation projects. Its directive system enables embedding code examples with syntax highlighting, generating tables of contents, creating cross-references between documents, and including automatically generated API documentation from source code docstrings. These capabilities make RST the preferred format for projects hosted on ReadTheDocs and documented with Sphinx.

The conversion process maps wiki elements to their RST equivalents: headings become underlined titles, wiki-style bold and italic become RST inline markup, lists maintain their hierarchy, and tables are reformatted using RST grid or simple table syntax. Wiki links are converted to RST cross-references or external hyperlinks, and structured content like code blocks gain proper RST directive wrappers with language specification for syntax highlighting.

Once in RST format, your documentation can be built with Sphinx into HTML websites, PDF documents, EPUB ebooks, and man pages from a single source. This multi-format capability, combined with the ability to store RST files in version control alongside source code, makes the wiki-to-RST conversion a valuable step in professionalizing any project's documentation infrastructure.

Key Benefits of Converting Wiki to RST:

• Sphinx Compatibility: Immediate use with Sphinx documentation generator
• Version Control: Store documentation alongside code in Git repositories
• Multi-Format Output: Build HTML, PDF, EPUB from single RST source
• Cross-References: Link between documents and sections with RST references
• Code Highlighting: Syntax-highlighted code blocks with language specification
• ReadTheDocs: Direct hosting on ReadTheDocs platform
• API Docs: Integrate with autodoc for automatic API reference generation

Practical Examples

Example 1: API Documentation Migration

Input Wiki file (api.wiki):

== API Reference ==

=== Authentication ===
All requests must include an '''API key''' in the header.

Authorization: Bearer YOUR_TOKEN

=== Endpoints ===
{| class="wikitable"
|-
! Method !! Endpoint !! Description
|-
| GET || /api/users || List all users
|-
| POST || /api/users || Create new user
|-
| DELETE || /api/users/{{id}} || Delete user
|}

Output RST file (api.rst):

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

Authentication
--------------
All requests must include an **API key** in the header.

``Authorization: Bearer YOUR_TOKEN``

Endpoints
---------
+--------+----------------+-----------------+
| Method | Endpoint       | Description     |
+========+================+=================+
| GET    | /api/users     | List all users  |
+--------+----------------+-----------------+
| POST   | /api/users     | Create new user |
+--------+----------------+-----------------+
| DELETE | /api/users/:id | Delete user     |
+--------+----------------+-----------------+

Example 2: Installation Guide Wiki to RST

Input Wiki file (install.wiki):

== Installation Guide ==

=== Requirements ===
* Python 3.8 or higher
* pip package manager
* Virtual environment (recommended)

=== Steps ===
# Clone the repository
# Create a virtual environment
# Install dependencies
# Run the setup script

''Note: See [[Troubleshooting]] for common issues.''

Output RST file (install.rst):

Installation Guide
==================

Requirements
------------
* Python 3.8 or higher
* pip package manager
* Virtual environment (recommended)

Steps
-----
#. Clone the repository
#. Create a virtual environment
#. Install dependencies
#. Run the setup script

*Note: See* :doc:`troubleshooting` *for common issues.*

Example 3: Feature Description to Sphinx Documentation

Input Wiki file (features.wiki):

== Key Features ==

=== Real-Time Processing ===
The system processes data in '''real-time''' with
sub-millisecond latency.

=== Scalability ===
Supports horizontal scaling across multiple nodes:
* Auto-scaling based on load
* Load balancing included
* Zero-downtime deployments

=== Security ===
Enterprise-grade security with:
* End-to-end encryption
* Role-based access control
* Audit logging

Output RST file (features.rst):

Key Features
============

Real-Time Processing
--------------------
The system processes data in **real-time** with
sub-millisecond latency.

Scalability
-----------
Supports horizontal scaling across multiple nodes:

* Auto-scaling based on load
* Load balancing included
* Zero-downtime deployments

Security
--------
Enterprise-grade security with:

* End-to-end encryption
* Role-based access control
* Audit logging

Frequently Asked Questions (FAQ)

Q: What is reStructuredText (RST)?

A: reStructuredText is a markup language designed for creating technical documentation. Developed as part of the Python Docutils project, RST uses underlined headings, asterisk-based emphasis, and a powerful directive system for embedding code, images, notes, and warnings. It is the native input format for the Sphinx documentation generator used by most Python projects.

Q: How do wiki headings translate to RST?

A: Wiki headings (== Heading ==, === Subheading ===) are converted to RST underlined headings. RST uses underline characters (=, -, ~, ^) to denote heading levels. The first level uses equals signs, the second uses dashes, and so on. The underline must be at least as long as the heading text.

Q: Will wiki tables convert properly to RST?

A: Yes, wiki tables are converted to RST grid tables or simple tables. RST grid tables use +, -, and | characters to draw cell borders, with = for header row separators. While the syntax is more verbose than wiki tables, the result is well-formatted and compatible with Sphinx for rendering into HTML and PDF.

Q: Can I use the RST output with Sphinx immediately?

A: Yes, the converted RST files are valid Sphinx input. Add them to your Sphinx project's source directory, reference them in the toctree directive of your index.rst file, and run sphinx-build to generate HTML, PDF, or other output formats. You may want to adjust cross-references to match your project's document structure.

Q: What happens to wiki internal links?

A: Wiki internal links ([[Page Name]]) are converted to RST cross-references using the :doc: role or plain text with a note about the original link target. Since RST cross-references depend on the Sphinx project structure, you may need to adjust these references to point to the correct document paths in your documentation tree.

Q: Is RST better than Markdown for documentation?

A: RST has more built-in features than Markdown for technical documentation: directives for code blocks, warnings, and notes; roles for inline semantics; cross-reference capabilities; and native Sphinx integration. Markdown is simpler and more widely known but requires extensions for many features RST provides natively. For Python projects and comprehensive documentation, RST is generally preferred.

Q: How does the converter handle wiki code blocks?

A: Wiki code blocks (using <code>, <pre>, or <source> tags) are converted to RST code-block directives with appropriate language specification. Inline code is wrapped in double backticks (``code``). The RST code-block directive supports syntax highlighting for dozens of programming languages when rendered with Sphinx.

Q: Can I host the converted RST documentation on ReadTheDocs?

A: Yes, ReadTheDocs is built specifically for Sphinx and RST documentation. Once your wiki content is converted to RST and structured as a Sphinx project, you can connect your Git repository to ReadTheDocs for automatic documentation building and hosting. ReadTheDocs provides versioning, search, and PDF generation for free for open-source projects.