Conversor online gratuito de ASCIIDOC para RST

Um projeto Sphinx ou Docutils requer arquivos reStructuredText, mas a documentação de origem está escrita em AsciiDoc. A conversão preserva a documentação reutilizável como arquivos .rst para edição, controle de versão e compilações de documentação Python.

O que é o formato ASCIIDOC

AsciiDoc é uma linguagem de marcação leve para manuais, arquivos README, livros, documentação de API e sites técnicos. Os arquivos normalmente usam as extensões .adoc ou .asciidoc e são criados ou processados por Asciidoctor, AsciiDoc, Antora e sistemas de compilação de documentação que incorporam AsciiDoc. Sua sintaxe inclui títulos, atributos, referências cruzadas, advertências, tabelas, blocos de código-fonte, inclusões e macros.

O que é o formato RST

reStructuredText, geralmente abreviado como RST, é um formato de marcação em texto simples usado pelo Docutils, Sphinx, pela documentação de pacotes Python e por alguns geradores de sites estáticos. Ele oferece suporte a títulos estruturados, diretivas, funções, notas de rodapé, referências, tabelas, blocos de código literal e arquivos incluídos. RST é o formato de origem nativo do Sphinx, portanto é apropriado quando um projeto de documentação já depende de conf.py, diretivas do Sphinx ou da cadeia de ferramentas de documentação Python.

Como converter ASCIIDOC para RST na prática

O fluxo de trabalho de linha de comando mais confiável consiste em deixar o Asciidoctor interpretar a origem, gerar DocBook XML e deixar o Pandoc gravar RST:

1. Instale Asciidoctor e Pandoc usando o gerenciador de pacotes do seu sistema operacional ou seguindo as instruções de instalação dos projetos.
2. Altere para o diretório que contém o arquivo de origem e verifique se as imagens referenciadas e os arquivos incluídos estão disponíveis.
3. Execute o pipeline de conversão:

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

Substitua manual.adoc e manual.rst pelos nomes de arquivo reais. O Asciidoctor processa atributos, condicionais, inclusões e a sintaxe AsciiDoc antes que o Pandoc converta a estrutura DocBook resultante. Para obter um arquivo intermediário separado, use asciidoctor -b docbook5 -o manual.xml manual.adoc, seguido de pandoc -f docbook -t rst -o manual.rst manual.xml.

Você também pode converter o arquivo gratuitamente no site 101convert.com sem instalar software. Verifique manualmente o RST gerado antes de adicioná-lo a um projeto Sphinx.

Limites de qualidade e compatibilidade

Esta é uma conversão estrutural, e não uma substituição sintática individual. Atributos do AsciiDoc, macros personalizadas, IDs de recursos do Antora, tabelas complexas, conteúdo incorporado e extensões do Asciidoctor podem não ter um equivalente direto em RST. A saída intermediária do DocBook também pode alterar destinos de referências cruzadas, caminhos de imagens, advertências e opções de blocos de código.

Compile o resultado com sphinx-build ou Docutils e corrija os avisos sobre diretivas desconhecidas, referências não resolvidas, tabelas malformadas e imagens ausentes. Os títulos RST usam sublinhados em vez de marcadores de título do AsciiDoc, e diretivas específicas do Sphinx, como .. toctree::, geralmente exigem inserção manual após a conversão.