Convert AsciiDoc to RST

Why Convert AsciiDoc to RST?

Converting AsciiDoc to reStructuredText (RST) is essential when migrating documentation to the Python ecosystem or integrating with Sphinx-based documentation systems. While both formats serve similar purposes as lightweight markup languages for technical writing, RST is the standard format for Python project documentation, the Sphinx documentation generator, and Read the Docs hosting platform. If your project is moving to a Python-centric toolchain, converting from AsciiDoc to RST ensures seamless integration.

AsciiDoc and RST share many conceptual similarities -- both support headings, lists, tables, code blocks, cross-references, and admonitions. However, they differ significantly in syntax. AsciiDoc uses = for headings, while RST uses underline characters. AsciiDoc tables use | delimiters directly, while RST requires grid or simple table formats. The conversion handles these syntactic differences automatically, mapping AsciiDoc constructs to their RST equivalents while preserving document structure and content.

RST's greatest strength lies in its extensible directive system and deep integration with Sphinx. Sphinx provides automatic API documentation generation through autodoc, cross-project referencing with intersphinx, and a rich theme ecosystem. For Python libraries, frameworks, and tools, RST with Sphinx remains the gold standard for documentation. Converting existing AsciiDoc documentation to RST enables teams to leverage these powerful features without rewriting content from scratch.

Many prominent projects use RST and Sphinx, including the Python standard library, Django, Flask, NumPy, and the Linux kernel documentation. By converting to RST, your documentation becomes compatible with this established ecosystem and can be hosted on platforms like Read the Docs that provide automatic building, versioning, and search capabilities for RST-based documentation.

Key Benefits of Converting AsciiDoc to RST:

• Sphinx Integration: Full compatibility with the Sphinx documentation generator
• Python Ecosystem: Standard format for Python package and library documentation
• Read the Docs: Direct deployment to the popular documentation hosting platform
• Autodoc Support: Automatic API documentation from Python source code docstrings
• Cross-Referencing: Rich intersphinx links between documentation projects
• Theme Ecosystem: Access to numerous Sphinx themes and extensions
• Community Standard: Aligns with documentation practices of major Python projects

Practical Examples

Example 1: Technical Documentation Migration

Input AsciiDoc file (guide.adoc):

= Installation Guide
:author: Development Team

== Prerequisites

Before installing, ensure you have:

* Python 3.8 or later
* pip package manager
* Virtual environment tool

== Installation Steps

Install the package using pip:

[source,bash]
----
pip install mypackage
----

NOTE: Use a virtual environment for isolation.

Output RST file (guide.rst):

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

Prerequisites
=============

Before installing, ensure you have:

* Python 3.8 or later
* pip package manager
* Virtual environment tool

Installation Steps
==================

Install the package using pip:

.. code-block:: bash

   pip install mypackage

.. note::

   Use a virtual environment for isolation.

Example 2: API Reference Documentation

Input AsciiDoc file (api-ref.adoc):

== API Reference

=== UserService Class

The `UserService` class handles user operations.

.Methods
|===
| Method | Parameters | Returns

| `create_user` | name, email | User object
| `delete_user` | user_id | Boolean
| `get_user` | user_id | User object
|===

WARNING: All methods require authentication.

Output RST file (api-ref.rst):

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

UserService Class
-----------------

The ``UserService`` class handles user operations.

Methods:

+-----------------+-------------+-------------+
| Method          | Parameters  | Returns     |
+=================+=============+=============+
| ``create_user`` | name, email | User object |
+-----------------+-------------+-------------+
| ``delete_user`` | user_id     | Boolean     |
+-----------------+-------------+-------------+
| ``get_user``    | user_id     | User object |
+-----------------+-------------+-------------+

.. warning::

   All methods require authentication.

Example 3: Configuration Documentation

Input AsciiDoc file (config.adoc):

= Configuration Reference

== Environment Variables

DATABASE_URL::
  Connection string for the database.
  Example: `postgresql://localhost/mydb`

SECRET_KEY::
  Application secret key for signing.
  Must be at least 32 characters.

TIP: Store secrets in environment variables,
never in source code.

Output RST file (config.rst):

=======================
Configuration Reference
=======================

Environment Variables
=====================

DATABASE_URL
  Connection string for the database.
  Example: ``postgresql://localhost/mydb``

SECRET_KEY
  Application secret key for signing.
  Must be at least 32 characters.

.. tip::

   Store secrets in environment variables,
   never in source code.

Frequently Asked Questions (FAQ)

Q: What is the main difference between AsciiDoc and RST?

A: Both are lightweight markup languages for technical documentation, but they differ in syntax and ecosystem. AsciiDoc uses = for headings, * for bold, and has a simpler table syntax. RST uses underline characters for headings, ** for bold, and has a more complex but flexible directive system. AsciiDoc is popular in Java/polyglot projects, while RST is the standard in the Python ecosystem and powers Sphinx documentation.

Q: Why would I choose RST over AsciiDoc?

A: Choose RST if your project is Python-based and you want to use Sphinx for documentation generation, autodoc for automatic API documentation from docstrings, Read the Docs for hosting, or intersphinx for cross-project references. RST is the community standard for Python packages, and most Python developers are familiar with it. If your documentation needs to integrate with Python tooling, RST is the better choice.

Q: Are all AsciiDoc features supported in RST?

A: Most AsciiDoc features have direct RST equivalents: headings, lists, tables, code blocks, admonitions, cross-references, and include directives all map well between the formats. Some AsciiDoc-specific features like conditional preprocessing (ifdef) require Sphinx extensions in RST. Conversely, RST offers features not available in AsciiDoc, such as the autodoc directive for Python source documentation and the extensive Sphinx extension ecosystem.

Q: How does the conversion handle AsciiDoc tables?

A: AsciiDoc tables using | delimiters are converted to RST grid tables with proper alignment characters (+, -, |, =). Simple two-column tables may be converted to RST simple tables for readability. Column spans and header rows are preserved in the conversion. RST table syntax is more verbose but provides equivalent functionality for all standard AsciiDoc table configurations.

Q: Will code blocks with syntax highlighting be preserved?

A: Yes. AsciiDoc source blocks ([source,python]) are converted to RST code-block directives (.. code-block:: python) with the language specifier preserved. Both formats support syntax highlighting through their respective toolchains (Asciidoctor uses Rouge or CodeRay; Sphinx uses Pygments). The indented code content is properly reformatted to meet RST's indentation requirements.

Q: Can I use the converted RST files with Sphinx immediately?

A: Yes, the converted RST files are valid Sphinx-compatible reStructuredText. You can place them in a Sphinx project's source directory and build HTML, PDF, or EPUB output immediately. You may need to add the files to your index.rst toctree directive and adjust any cross-references to match your project's document structure. Sphinx-specific directives like autodoc would need to be added manually.

Q: How are AsciiDoc admonitions converted to RST?

A: AsciiDoc admonitions (NOTE:, TIP:, WARNING:, IMPORTANT:, CAUTION:) are converted to their RST directive equivalents (.. note::, .. tip::, .. warning::, .. important::, .. caution::). Both formats support the same set of admonition types. Block-style admonitions in AsciiDoc (using ====) are also properly converted to RST directive syntax with appropriate indentation.

Q: What about AsciiDoc include directives?

A: AsciiDoc include directives (include::filename[]) are converted to RST include directives (.. include:: filename). Tag-based partial includes (include::file[tags=section]) may require adjustment in RST, as Sphinx uses different mechanisms for partial file inclusion. Level offset attributes are handled by adjusting heading levels in the included content or using Sphinx's :start-after: and :end-before: options.