Convertidor online gratuito de ASCIIDOC a RST

Un proyecto de Sphinx o Docutils requiere archivos reStructuredText, pero la documentación de origen está escrita en AsciiDoc. La conversión conserva la documentación reutilizable como archivos .rst para su edición, control de versiones y compilaciones de documentación de Python.

Qué es el formato ASCIIDOC

AsciiDoc es un lenguaje de marcado ligero para manuales, archivos README, libros, documentación de API y sitios web técnicos. Los archivos suelen usar las extensiones .adoc o .asciidoc y se crean o procesan mediante Asciidoctor, AsciiDoc, Antora y sistemas de compilación de documentación que integran AsciiDoc. Su sintaxis incluye encabezados, atributos, referencias cruzadas, admonitions, tablas, bloques de código fuente, inclusiones y macros.

Qué es el formato RST

reStructuredText, normalmente abreviado como RST, es un formato de marcado de texto plano utilizado por Docutils, Sphinx, la documentación de paquetes de Python y algunos generadores de sitios estáticos. Admite encabezados estructurados, directivas, roles, notas al pie, referencias, tablas, bloques de código literal y archivos incluidos. RST es el formato de origen nativo de Sphinx, por lo que resulta apropiado cuando un proyecto de documentación ya depende de conf.py, directivas de Sphinx o la cadena de herramientas de documentación de Python.

Cómo convertir realmente ASCIIDOC a RST

El flujo de trabajo de línea de comandos más fiable consiste en permitir que Asciidoctor interprete el origen, genere DocBook XML y que Pandoc escriba RST:

1. Instale Asciidoctor y Pandoc mediante el administrador de paquetes de su sistema operativo o siguiendo las instrucciones de instalación de los proyectos.
2. Cambie al directorio que contiene el archivo de origen y verifique que las imágenes referenciadas y los archivos incluidos estén disponibles.
3. Ejecute la canalización de conversión:

asciidoctor -b docbook5 -o - manual.adoc | pandoc -f docbook -t rst -o manual.rst

Sustituya manual.adoc y manual.rst por los nombres de archivo reales. Asciidoctor procesa los atributos, condicionales, inclusiones y la sintaxis de AsciiDoc antes de que Pandoc convierta la estructura DocBook resultante. Para usar un archivo intermedio independiente, utilice asciidoctor -b docbook5 -o manual.xml manual.adoc, seguido de pandoc -f docbook -t rst -o manual.rst manual.xml.

También puede convertir el archivo de forma gratuita en el sitio web 101convert.com sin instalar software. Compruebe manualmente el RST generado antes de añadirlo a un proyecto de Sphinx.

Limitaciones de calidad y compatibilidad

Esta es una conversión estructural, no una sustitución de sintaxis uno a uno. Es posible que los atributos de AsciiDoc, las macros personalizadas, los identificadores de recursos de Antora, las tablas complejas, el contenido incrustado y las extensiones de Asciidoctor no tengan un equivalente directo en RST. El resultado intermedio de DocBook también puede modificar los destinos de las referencias cruzadas, las rutas de las imágenes, las admonitions y las opciones de los bloques de código.

Compile el resultado con sphinx-build o Docutils y corrija las advertencias sobre directivas desconocidas, referencias sin resolver, tablas con formato incorrecto e imágenes faltantes. Los encabezados de RST utilizan subrayados en lugar de marcadores de encabezado de AsciiDoc, y las directivas específicas de Sphinx, como .. toctree::, normalmente requieren una inserción manual después de la conversión.