Convertisseur en ligne gratuit de AD en RST

RST est requis par des systèmes de documentation tels que Sphinx et Docutils, tandis qu’un fichier AD peut être un ancien document en texte brut ou une exportation de texte propre à une application. Sa conversion permet d’utiliser le contenu lisible dans une documentation basée sur RST, un système de contrôle de version et des générations de sites statiques.

Qu’est-ce que le format AD ?

AD n’est pas un format texte standardisé unique. Cette extension est utilisée par différents outils de documentation hérités, des applications personnalisées et des programmes d’exportation en texte brut. Le programme qui crée le fichier détermine si celui-ci contient des paragraphes ordinaires, des enregistrements structurés, du balisage, des tableaux ou des commandes propres à l’application.

Ouvrez d’abord le fichier dans un éditeur de texte. S’il contient du texte lisible et des titres, listes ou balises reconnaissables, il peut généralement être adapté à RST. S’il contient des données binaires ou des caractères de contrôle illisibles, identifiez l’application d’origine et exportez le fichier depuis cette application vers du texte brut, du HTML ou un autre format documenté avant de le convertir.

Qu’est-ce que le format RST ?

RST, ou reStructuredText, est un format de balisage léger utilisé par Docutils, Sphinx et les projets de documentation Python. Il représente les titres avec des soulignements, les listes avec une indentation, les liens avec des cibles explicites, le code littéral avec une indentation et les directives telles que .. note::.

RST reste lisible sous forme de texte brut et fonctionne bien avec Git, la revue de code, les générations automatisées de documentation, les références croisées, les tableaux et la production de fichiers HTML ou PDF. Il est préférable lorsque le système cible accepte spécifiquement reStructuredText plutôt que Markdown ou HTML.

Comment convertir réellement AD en RST

1. Effectuez une sauvegarde du fichier original source.ad.
2. Ouvrez-le dans un éditeur compatible avec UTF-8, tel que Visual Studio Code, Notepad++ ou un autre éditeur de texte brut. Vérifiez l’encodage des caractères et supprimez les en-têtes propres à l’application qui ne font pas partie du document.
3. Identifiez la structure AD : lignes de titre, paragraphes, listes, tableaux, liens, sections de code et images intégrées. Il n’existe aucun analyseur AD universel : la syntaxe source doit donc être interprétée avant de pouvoir être convertie en RST.
4. Réécrivez les titres à l’aide d’un caractère de soulignement dont la longueur correspond à celle du titre. Par exemple :
   Installation ============ Install the package with:: pip install package-name
5. Convertissez les listes simples en marqueurs RST tels que * item ou #. numbered item. Indentez les lignes de continuation de manière cohérente.
6. Remplacez les liens, champs et directives propres à AD par leurs équivalents RST. Utilisez .. image:: filename.png pour les images et .. code-block:: python pour le code avec coloration syntaxique.
7. Enregistrez le résultat sous output.rst en utilisant l’encodage UTF-8.
8. Générez ou validez le résultat avec Docutils ou Sphinx. Un projet Sphinx peut être vérifié avec sphinx-build -b html . _build/html ; les erreurs de conversion et les directives mal formées apparaîtront dans la sortie de génération.

Pour un fichier AD simple contenant des paragraphes ordinaires, le convertisseur intégré de 101convert.com peut convertir le fichier en ligne et gratuitement, sans installer de logiciel. Vérifiez ensuite le RST généré, car la conversion automatique ne peut pas déterminer de manière fiable le balisage AD propre à une application.

Si le fichier AD contient en réalité du contenu similaire à Markdown, Pandoc peut effectuer la conversion de syntaxe après confirmation du format d’entrée : pandoc source.ad -f markdown -t rst -o output.rst. N’utilisez pas -f markdown simplement parce que l’extension est .ad ; cette option est correcte uniquement lorsque le contenu du fichier suit la syntaxe Markdown.

Limites de qualité et de compatibilité

Les paragraphes simples et les listes de base sont généralement transférés avec peu de pertes. Les niveaux de titre, les listes imbriquées, les tableaux, la mise en forme inline, les ancres, les images et les commandes AD personnalisées nécessitent une vérification manuelle, car RST les exprime différemment.

RST traite l’indentation comme une syntaxe. Un espace mal placé peut modifier une liste, un bloc littéral ou une directive, et une erreur dans les séparateurs de colonnes peut empêcher la génération d’un tableau. Vérifiez les caractères non ASCII, les chemins d’image relatifs, les liens externes, les notes de bas de page et toutes les métadonnées AD après la conversion.

Renommer .ad en .rst ne convertit pas le contenu. Cela modifie uniquement le nom du fichier et peut amener Docutils ou Sphinx à signaler des erreurs d’analyse.