Darmowy konwerter online ASCIIDOC do RST

Projekt Sphinx lub Docutils wymaga plików reStructuredText, ale dokumentacja źródłowa jest zapisana w AsciiDoc. Konwersja zachowuje wielokrotnego użytku dokumentację jako pliki .rst do edycji, kontroli wersji i kompilowania dokumentacji Pythona.

Czym jest format ASCIIDOC

AsciiDoc to lekki język znaczników używany do tworzenia podręczników, plików README, książek, dokumentacji API i technicznych witryn internetowych. Pliki zwykle korzystają z rozszerzeń .adoc lub .asciidoc i są tworzone lub przetwarzane przez Asciidoctor, AsciiDoc, Antora oraz systemy kompilowania dokumentacji obsługujące AsciiDoc. Jego składnia obejmuje nagłówki, atrybuty, odsyłacze, admonitions, tabele, bloki kodu źródłowego, dołączanie plików i makra.

Czym jest format RST

reStructuredText, zwykle skracany do RST, to tekstowy format znaczników używany przez Docutils, Sphinx, dokumentację pakietów Pythona i niektóre generatory witryn statycznych. Obsługuje uporządkowane nagłówki, dyrektywy, role, przypisy, odsyłacze, tabele, dosłowne bloki kodu i dołączane pliki. RST jest natywnym formatem źródłowym Sphinx, dlatego sprawdza się, gdy projekt dokumentacji już korzysta z conf.py, dyrektyw Sphinx lub zestawu narzędzi dokumentacji Pythona.

Jak faktycznie przekonwertować ASCIIDOC do RST

Najbardziej niezawodny sposób pracy z wiersza poleceń polega na tym, aby Asciidoctor zinterpretował źródło, wygenerował DocBook XML, a Pandoc zapisał wynik w formacie RST:

1. Zainstaluj Asciidoctor i Pandoc za pomocą menedżera pakietów systemu operacyjnego lub zgodnie z instrukcjami instalacji projektów.
2. Przejdź do katalogu zawierającego plik źródłowy i sprawdź, czy wskazane obrazy oraz dołączane pliki są dostępne.
3. Uruchom potok konwersji:

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

Zastąp manual.adoc i manual.rst rzeczywistymi nazwami plików. Asciidoctor przetwarza atrybuty, instrukcje warunkowe, dołączane pliki i składnię AsciiDoc, zanim Pandoc przekonwertuje wynikową strukturę DocBook. Aby utworzyć osobny plik pośredni, użyj polecenia asciidoctor -b docbook5 -o manual.xml manual.adoc, a następnie pandoc -f docbook -t rst -o manual.rst manual.xml.

Możesz również bezpłatnie przekonwertować plik w witrynie 101convert.com bez instalowania oprogramowania. Przed dodaniem wygenerowanego RST do projektu Sphinx sprawdź go ręcznie.

Ograniczenia jakości i zgodności

Jest to konwersja strukturalna, a nie zastąpienie składni jeden do jednego. Atrybuty AsciiDoc, niestandardowe makra, identyfikatory zasobów Antora, złożone tabele, osadzona zawartość i rozszerzenia Asciidoctor mogą nie mieć bezpośrednich odpowiedników w RST. Pośredni wynik DocBook może również zmienić cele odsyłaczy, ścieżki obrazów, admonitions i opcje bloków kodu.

Zbuduj wynik za pomocą sphinx-build lub Docutils i popraw ostrzeżenia dotyczące nieznanych dyrektyw, nierozwiązanych odsyłaczy, nieprawidłowo sformatowanych tabel oraz brakujących obrazów. Nagłówki RST używają podkreśleń zamiast znaczników nagłówków AsciiDoc, a dyrektywy właściwe dla Sphinx, takie jak .. toctree::, zwykle wymagają ręcznego dodania po konwersji.