Convert ADOC to RST

Why Convert ADOC to RST?

Converting AsciiDoc to reStructuredText enables seamless integration with the Python documentation ecosystem, particularly Sphinx and ReadTheDocs. While AsciiDoc offers excellent features for writing books and general technical documentation, RST is the native format for Sphinx, the documentation generator that powers the official Python documentation and thousands of open-source project docs.

Sphinx provides powerful features specifically designed for software documentation, including automatic API documentation generation (autodoc), sophisticated cross-referencing across documents and code, and built-in support for multiple output formats. By converting to RST, you can leverage these features while also gaining access to the extensive Sphinx extension ecosystem.

ReadTheDocs offers free documentation hosting with automatic builds from Git repositories, versioned documentation, and excellent SEO. RST documents work seamlessly with ReadTheDocs, enabling continuous documentation deployment. This makes RST the format of choice for open-source Python projects seeking professional documentation hosting.

The conversion preserves your document structure, headings, code blocks, tables, and admonitions. AsciiDoc's single-line headings become RST's underline-based headings, code blocks are converted to RST code-block directives, and admonitions are mapped to their RST equivalents. Cross-references and anchors are also converted to maintain document navigation.

Key Benefits of Converting ADOC to RST:

• Sphinx Integration: RST is Sphinx's native format with full feature support
• ReadTheDocs Publishing: Free hosting with automatic builds and versioning
• Python Autodoc: Generate API documentation from Python docstrings
• Cross-References: Powerful linking across documents, modules, and classes
• Extension Ecosystem: Hundreds of Sphinx extensions available
• Version Documentation: Support multiple doc versions from branches
• Scientific Community: Standard format for NumPy, SciPy, Pandas docs

Practical Examples

Example 1: API Documentation with Code Examples

Input ADOC file (api_reference.adoc):

= API Reference
:toc:

== Installation

Install the package using pip:

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

== Quick Start

Here's a basic usage example:

[source,python]
----
from mypackage import Client

client = Client(api_key="your-key")
result = client.process(data)
print(result)
----

NOTE: Always keep your API key secure.

== Configuration Options

|===
|Option |Type |Default |Description

|timeout |int |30 |Request timeout in seconds
|retries |int |3 |Number of retry attempts
|debug |bool |false |Enable debug logging
|===

Output RST file (api_reference.rst):

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

.. contents:: Table of Contents
   :local:

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

Install the package using pip:

.. code-block:: bash

   pip install mypackage

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

Here's a basic usage example:

.. code-block:: python

   from mypackage import Client

   client = Client(api_key="your-key")
   result = client.process(data)
   print(result)

.. note::

   Always keep your API key secure.

Configuration Options
---------------------

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

   * - Option
     - Type
     - Default
     - Description
   * - timeout
     - int
     - 30
     - Request timeout in seconds
   * - retries
     - int
     - 3
     - Number of retry attempts
   * - debug
     - bool
     - false
     - Enable debug logging

Example 2: Tutorial with Cross-References

Input ADOC file (tutorial.adoc):

= Getting Started Guide
:author: Documentation Team

== Introduction
[[intro]]

Welcome to the tutorial. This guide covers:

* Basic concepts
* Advanced features (see <<advanced>>)
* Best practices

== Basic Concepts

=== Variables

Variables store data for later use.

.Example Variable Declaration
[source,python]
----
name = "Alice"
age = 30
----

=== Functions

Functions encapsulate reusable logic.

== Advanced Topics
[[advanced]]

As mentioned in <<intro>>, this section covers advanced material.

TIP: Read the basics first before attempting advanced topics.

Output RST file (tutorial.rst):

Getting Started Guide
=====================

:Author: Documentation Team

.. _intro:

Introduction
------------

Welcome to the tutorial. This guide covers:

* Basic concepts
* Advanced features (see :ref:`advanced`)
* Best practices

Basic Concepts
--------------

Variables
^^^^^^^^^

Variables store data for later use.

**Example Variable Declaration**

.. code-block:: python

   name = "Alice"
   age = 30

Functions
^^^^^^^^^

Functions encapsulate reusable logic.

.. _advanced:

Advanced Topics
---------------

As mentioned in :ref:`intro`, this section covers advanced material.

.. tip::

   Read the basics first before attempting advanced topics.

Example 3: Module Documentation for Sphinx

Input ADOC file (utils_module.adoc):

= Utils Module
:source-highlighter: highlight.js

== Overview

The utils module provides helper functions for common operations.

== Functions

=== format_date

Formats a date object to a string.

.Parameters
* `date` - The date object to format
* `pattern` - The output format pattern (default: "YYYY-MM-DD")

.Returns
A formatted date string.

.Example
[source,python]
----
from utils import format_date
from datetime import datetime

result = format_date(datetime.now(), "DD/MM/YYYY")
# Returns: "15/01/2024"
----

WARNING: Invalid date objects will raise ValueError.

Output RST file (utils_module.rst):

Utils Module
============

Overview
--------

The utils module provides helper functions for common operations.

Functions
---------

format_date
^^^^^^^^^^^

Formats a date object to a string.

**Parameters**

* ``date`` - The date object to format
* ``pattern`` - The output format pattern (default: "YYYY-MM-DD")

**Returns**

A formatted date string.

**Example**

.. code-block:: python

   from utils import format_date
   from datetime import datetime

   result = format_date(datetime.now(), "DD/MM/YYYY")
   # Returns: "15/01/2024"

.. warning::

   Invalid date objects will raise ValueError.

Frequently Asked Questions (FAQ)

Q: Will my ADOC headings convert correctly to RST heading underlines?

A: Yes, the converter transforms AsciiDoc's single-line heading syntax (= Title, == Section) into RST's underline-based headings. The hierarchy is preserved, with appropriate underline characters (=, -, ^, ~) used for each heading level following RST conventions.

Q: How are code blocks converted between formats?

A: AsciiDoc's [source,language] blocks are converted to RST's .. code-block:: language directive. The language specification, code content, and indentation are preserved. Callouts and line highlighting may require manual adjustment after conversion.

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

A: Yes, the converted RST files are compatible with Sphinx. You'll need to add them to your Sphinx project's source directory and include them in your toctree. Some Sphinx-specific directives like :ref: and :doc: may need manual refinement for optimal cross-referencing.

Q: How are AsciiDoc tables converted to RST format?

A: AsciiDoc tables are converted to RST list-tables or grid tables depending on complexity. Simple tables become list-tables with proper column headers. Complex tables with merged cells may require manual adjustment due to differences in table syntax between the formats.

Q: What happens to AsciiDoc admonitions (NOTE, WARNING, TIP)?

A: AsciiDoc admonitions are converted to their RST directive equivalents: .. note::, .. warning::, .. tip::, etc. The content is properly indented under the directive, maintaining the same visual distinction in rendered output.

Q: Are cross-references and anchors preserved during conversion?

A: Yes, AsciiDoc anchors ([[anchor-name]]) are converted to RST labels (.. _anchor-name:), and cross-references are converted to RST references (:ref:`anchor-name`). This maintains document navigation in the converted RST files.

Q: Can I publish the converted RST to ReadTheDocs?

A: Absolutely. Once converted, your RST files can be added to a Sphinx project and published to ReadTheDocs. You'll need a conf.py file, requirements.txt, and .readthedocs.yaml configuration. ReadTheDocs will automatically build and host your documentation with versioning support.

Q: How do include directives translate between formats?

A: AsciiDoc's include::file.adoc[] directive converts to RST's .. include:: file.rst directive. Note that included files must also be converted to RST format. For modular documentation, ensure all component files are converted and paths are updated accordingly.