Convertitore online gratuito da ASCIIDOC a RST

Un progetto Sphinx o Docutils richiede file reStructuredText, ma la documentazione sorgente è scritta in AsciiDoc. La conversione conserva la documentazione riutilizzabile come file .rst per la modifica, il controllo versione e le build della documentazione Python.

Cos'è il formato ASCIIDOC

AsciiDoc è un linguaggio di markup leggero utilizzato per manuali, file README, libri, documentazione API e siti web tecnici. I file utilizzano comunemente le estensioni .adoc o .asciidoc e vengono creati o elaborati da Asciidoctor, AsciiDoc, Antora e dai sistemi di build della documentazione che integrano AsciiDoc. La sintassi include titoli, attributi, riferimenti incrociati, avvisi, tabelle, blocchi di codice sorgente, inclusioni e macro.

Cos'è il formato RST

reStructuredText, generalmente abbreviato in RST, è un formato di markup in testo semplice utilizzato da Docutils, Sphinx, dalla documentazione dei pacchetti Python e da alcuni generatori di siti statici. Supporta titoli strutturati, direttive, ruoli, note a piè di pagina, riferimenti, tabelle, blocchi di codice letterale e file inclusi. RST è il formato sorgente nativo di Sphinx, quindi è appropriato quando un progetto di documentazione dipende già da conf.py, dalle direttive Sphinx o dalla toolchain di documentazione Python.

Come convertire effettivamente ASCIIDOC in RST

Il flusso di lavoro da riga di comando più affidabile consiste nel lasciare che Asciidoctor interpreti la sorgente, produca DocBook XML e lasciare che Pandoc scriva RST:

1. Installa Asciidoctor e Pandoc utilizzando il gestore dei pacchetti del tuo sistema operativo o le istruzioni di installazione dei progetti.
2. Passa alla directory contenente il file sorgente e verifica che le immagini referenziate e i file inclusi siano disponibili.
3. Esegui la pipeline di conversione:

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

Sostituisci manual.adoc e manual.rst con i nomi file effettivi. Asciidoctor elabora attributi, condizionali, inclusioni e sintassi AsciiDoc prima che Pandoc converta la struttura DocBook risultante. Per ottenere un file intermedio separato, usa asciidoctor -b docbook5 -o manual.xml manual.adoc, seguito da pandoc -f docbook -t rst -o manual.rst manual.xml.

Puoi anche convertire il file gratuitamente sul sito web 101convert.com senza installare software. Controlla manualmente l'RST generato prima di aggiungerlo a un progetto Sphinx.

Limiti di qualità e compatibilità

Si tratta di una conversione strutturale, non di una sostituzione sintattica uno a uno. Gli attributi AsciiDoc, le macro personalizzate, gli ID delle risorse Antora, le tabelle complesse, i contenuti incorporati e le estensioni Asciidoctor potrebbero non avere un equivalente diretto in RST. Anche l'output intermedio DocBook può modificare le destinazioni dei riferimenti incrociati, i percorsi delle immagini, gli avvisi e le opzioni dei blocchi di codice.

Compila il risultato con sphinx-build o Docutils e correggi gli avvisi relativi a direttive sconosciute, riferimenti irrisolti, tabelle malformate e immagini mancanti. I titoli RST utilizzano sottolineature anziché i marcatori dei titoli AsciiDoc, e direttive specifiche di Sphinx come .. toctree:: richiedono generalmente un inserimento manuale dopo la conversione.