Convertisseur en ligne gratuit de ASCIIDOC en RST

Un projet Sphinx ou Docutils nécessite des fichiers reStructuredText, mais la documentation source est écrite en AsciiDoc. La conversion conserve la documentation réutilisable sous forme de fichiers .rst pour la modification, le contrôle de version et les compilations de documentation Python.

Ce qu’est le format ASCIIDOC

AsciiDoc est un langage de balisage léger destiné aux manuels, fichiers README, livres, documentations d’API et sites web techniques. Les fichiers utilisent généralement les extensions .adoc ou .asciidoc et sont créés ou traités par Asciidoctor, AsciiDoc, Antora et les systèmes de compilation de documentation qui intègrent AsciiDoc. Sa syntaxe comprend des titres, des attributs, des références croisées, des avertissements, des tableaux, des blocs de code source, des inclusions et des macros.

Ce qu’est le format RST

reStructuredText, généralement abrégé en RST, est un format de balisage en texte brut utilisé par Docutils, Sphinx, la documentation des packages Python et certains générateurs de sites statiques. Il prend en charge les titres structurés, les directives, les rôles, les notes de bas de page, les références, les tableaux, les blocs de code littéraux et les fichiers inclus. RST est le format source natif de Sphinx ; il convient donc lorsqu’un projet de documentation dépend déjà de conf.py, de directives Sphinx ou de la chaîne d’outils de documentation Python.

Comment convertir concrètement ASCIIDOC en RST

La méthode en ligne de commande la plus fiable consiste à laisser Asciidoctor interpréter la source, produire du XML DocBook, puis laisser Pandoc générer du RST :

1. Installez Asciidoctor et Pandoc à l’aide du gestionnaire de packages de votre système d’exploitation ou en suivant les instructions d’installation des projets.
2. Placez-vous dans le répertoire contenant le fichier source et vérifiez que les images référencées et les fichiers inclus sont disponibles.
3. Exécutez le pipeline de conversion :

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

Remplacez manual.adoc et manual.rst par les noms de fichiers appropriés. Asciidoctor traite les attributs, les conditionnelles, les inclusions et la syntaxe AsciiDoc avant que Pandoc ne convertisse la structure DocBook obtenue. Pour utiliser un fichier intermédiaire distinct, exécutez asciidoctor -b docbook5 -o manual.xml manual.adoc, puis pandoc -f docbook -t rst -o manual.rst manual.xml.

Vous pouvez également convertir gratuitement le fichier sur le site web 101convert.com sans installer de logiciel. Vérifiez manuellement le RST généré avant de l’ajouter à un projet Sphinx.

Limites de qualité et de compatibilité

Il s’agit d’une conversion structurelle plutôt que d’une substitution syntaxique un à un. Les attributs AsciiDoc, les macros personnalisées, les identifiants de ressources Antora, les tableaux complexes, le contenu intégré et les extensions Asciidoctor peuvent ne pas avoir d’équivalent direct en RST. La sortie intermédiaire DocBook peut également modifier les cibles de références croisées, les chemins d’image, les avertissements et les options des blocs de code.

Compilez le résultat avec sphinx-build ou Docutils et corrigez les avertissements concernant les directives inconnues, les références non résolues, les tableaux mal formés et les images manquantes. Les titres RST utilisent des lignes de soulignement plutôt que les marqueurs de titre AsciiDoc, et les directives spécifiques à Sphinx telles que .. toctree:: doivent généralement être insérées manuellement après la conversion.