Online konvertor ASCIIDOC do RST zdarma

Projekt Sphinx nebo Docutils vyžaduje soubory reStructuredText, ale zdrojová dokumentace je napsaná v AsciiDoc. Převod zachová znovu použitelnou dokumentaci jako soubory .rst pro úpravy, správu verzí a sestavování dokumentace v Pythonu.

Co je formát ASCIIDOC

AsciiDoc je odlehčený značkovací jazyk pro příručky, soubory README, knihy, dokumentaci API a technické weby. Soubory běžně používají přípony .adoc nebo .asciidoc a vytvářejí se nebo zpracovávají pomocí Asciidoctor, AsciiDoc, Antora a systémů pro sestavování dokumentace, které vkládají AsciiDoc. Jeho syntaxe zahrnuje nadpisy, atributy, křížové odkazy, upozornění, tabulky, bloky zdrojového kódu, vkládání souborů a makra.

Co je formát RST

reStructuredText, obvykle zkracovaný na RST, je značkovací formát v prostém textu používaný nástroji Docutils, Sphinx, pro dokumentaci balíčků Pythonu a některými generátory statických webů. Podporuje strukturované nadpisy, direktivy, role, poznámky pod čarou, odkazy, tabulky, doslovné bloky kódu a vkládané soubory. RST je nativní zdrojový formát pro Sphinx, takže je vhodný, pokud projekt dokumentace již závisí na conf.py, direktivách Sphinx nebo nástrojovém řetězci pro dokumentaci Pythonu.

Jak skutečně převést ASCIIDOC na RST

Nejspolehlivější pracovní postup v příkazovém řádku spočívá v tom, že Asciidoctor interpretuje zdroj, vygeneruje DocBook XML a Pandoc zapíše RST:

1. Nainstalujte Asciidoctor a Pandoc pomocí správce balíčků svého operačního systému nebo podle instalačních pokynů příslušných projektů.
2. Přejděte do adresáře obsahujícího zdrojový soubor a ověřte, že jsou dostupné odkazované obrázky a vkládané soubory.
3. Spusťte převodní postup:

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

Nahraďte manual.adoc a manual.rst skutečnými názvy souborů. Asciidoctor zpracuje atributy, podmínky, vkládání souborů a syntaxi AsciiDoc ještě předtím, než Pandoc převede výslednou strukturu DocBook. Chcete-li vytvořit samostatný mezilehlý soubor, použijte asciidoctor -b docbook5 -o manual.xml manual.adoc a poté pandoc -f docbook -t rst -o manual.rst manual.xml.

Soubor můžete také bezplatně převést na webu 101convert.com bez instalace softwaru. Před přidáním vygenerovaného RST do projektu Sphinx jej ručně zkontrolujte.

Omezení kvality a kompatibility

Jedná se o strukturální převod, nikoli o nahrazení syntaxe jedna ku jedné. Atributy AsciiDoc, vlastní makra, identifikátory prostředků Antora, složité tabulky, vložený obsah a rozšíření Asciidoctor nemusí mít přímý ekvivalent v RST. Mezilehlý výstup DocBook může také změnit cíle křížových odkazů, cesty k obrázkům, upozornění a volby bloků kódu.

Výsledek sestavte pomocí sphinx-build nebo Docutils a opravte upozornění týkající se neznámých direktiv, nevyřešených odkazů, nesprávně vytvořených tabulek a chybějících obrázků. Nadpisy RST používají podtržení namísto značek nadpisů AsciiDoc a direktivy specifické pro Sphinx, například .. toctree::, obvykle vyžadují ruční vložení po převodu.