Konverter online gratis ASCIIDOC ke RST

Proyek Sphinx atau Docutils memerlukan file reStructuredText, tetapi dokumentasi sumber ditulis dalam AsciiDoc. Konversi ini mempertahankan dokumentasi yang dapat digunakan kembali sebagai file .rst untuk pengeditan, kontrol versi, dan build dokumentasi Python.

Apa itu format ASCIIDOC

AsciiDoc adalah bahasa markup ringan yang digunakan untuk manual, file README, buku, dokumentasi API, dan situs web teknis. File biasanya menggunakan ekstensi .adoc atau .asciidoc dan dibuat atau diproses oleh Asciidoctor, AsciiDoc, Antora, serta sistem build dokumentasi yang menyertakan AsciiDoc. Sintaksnya mencakup heading, atribut, referensi silang, admonition, tabel, blok kode sumber, include, dan makro.

Apa itu format RST

reStructuredText, biasanya disingkat RST, adalah format markup teks biasa yang digunakan oleh Docutils, Sphinx, dokumentasi paket Python, dan beberapa generator situs statis. Format ini mendukung heading terstruktur, direktif, role, catatan kaki, referensi, tabel, blok kode literal, dan file yang disertakan. RST adalah format sumber native untuk Sphinx, sehingga sesuai digunakan ketika proyek dokumentasi sudah bergantung pada conf.py, direktif Sphinx, atau toolchain dokumentasi Python.

Cara sebenarnya mengonversi ASCIIDOC ke RST

Alur kerja command-line yang paling andal adalah membiarkan Asciidoctor menginterpretasikan sumber, menghasilkan DocBook XML, lalu membiarkan Pandoc menulis RST:

1. Instal Asciidoctor dan Pandoc menggunakan package manager sistem operasi Anda atau petunjuk instalasi dari proyek tersebut.
2. Pindah ke direktori yang berisi file sumber dan verifikasi bahwa image yang dirujuk serta file yang disertakan tersedia.
3. Jalankan pipeline konversi:

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

Ganti manual.adoc dan manual.rst dengan nama file yang sebenarnya. Asciidoctor memproses atribut, kondisional, include, dan sintaks AsciiDoc sebelum Pandoc mengonversi struktur DocBook yang dihasilkan. Untuk file perantara terpisah, gunakan asciidoctor -b docbook5 -o manual.xml manual.adoc, kemudian pandoc -f docbook -t rst -o manual.rst manual.xml.

Anda juga dapat mengonversi file secara gratis di situs web 101convert.com tanpa menginstal software. Periksa RST yang dihasilkan secara manual sebelum menambahkannya ke proyek Sphinx.

Batasan kualitas dan kompatibilitas

Ini adalah konversi struktural, bukan penggantian sintaks satu banding satu. Atribut AsciiDoc, makro khusus, ID resource Antora, tabel kompleks, konten tersemat, dan ekstensi Asciidoctor mungkin tidak memiliki padanan langsung dalam RST. Output perantara DocBook juga dapat mengubah target referensi silang, jalur image, admonition, dan opsi blok kode.

Build hasilnya dengan sphinx-build atau Docutils dan perbaiki peringatan tentang direktif yang tidak dikenal, referensi yang tidak terselesaikan, tabel yang tidak valid, serta image yang hilang. Heading RST menggunakan garis bawah, bukan penanda heading AsciiDoc, dan direktif khusus Sphinx seperti .. toctree:: biasanya perlu ditambahkan secara manual setelah konversi.