Convertisseur reStructuredText vers HTML

Comment ça marche

reStructuredText est la langue de documentation du monde Python : le README.rst d'un paquet PyPI, la documentation écrite avec Sphinx et le CHANGELOG de nombreux projets libres l'utilisent. Quand vous voulez voir un tel fichier hors de GitHub, ou déplacer son contenu vers une page web, collez le texte ici. Par exemple, le titre « Installation » du README.rst de votre paquet, ses étapes numérotées, la commande pip introduite par :: et le tableau des options ressortent à droite en h2, ol, pre et table ; un bloc .. note:: devient un div intitulé « Note ». Le niveau des titres suit la règle de docutils : il est donné par l'ordre de première apparition de chaque caractère de soulignement, donc si vous avez utilisé = avant -, = est le niveau un et - le niveau deux. Structures prises en charge : titres soulignés ou surlignés, paragraphes, listes à puces et numérotées (imbriquées), listes de définitions et de champs, blocs de lignes, citations, transitions, blocs littéraux et doctest, tableaux simples et en grille, directives image, figure, code-block et encadrés, liens résolus par des cibles .. _nom:. Les directives propres à Sphinx comme toctree, contents et include sont ignorées et comptées dans la ligne de résultat, pas avalées en silence. La sortie est du code HTML : choisissez « Fragment » pour l'intégrer à une page et « Page complète » pour l'ouvrir comme fichier.

Cet outil est aussi connu sous le nom de convertir rst en html, rst vers html, restructuredtext en html, ouvrir un fichier rst, rst to html, apercu readme.rst.

Qu'est-ce que reStructuredText (RST) ?

reStructuredText est le langage de balisage en texte brut que la communauté Python utilise depuis 2002 ; son extension de fichier est .rst. Un titre s'écrit avec une ligne de ===== ou de ----- en dessous, l'emphase avec des *astérisques*, le code avec des ``doubles accents graves`` et un lien selon le motif `texte <adresse>`_. Ce qui le distingue de Markdown, ce sont les directives : des blocs comme .. note::, .. image:: et .. code-block:: donnent au document une structure extensible. Les README.rst des paquets PyPI, les sites de documentation produits avec Sphinx et la documentation de Python lui-même sont écrits dans ce langage ; le convertisseur de référence est docutils.

Qu'est-ce que HTML ?

Le HTML est la langue des pages que comprend un navigateur : il marque la structure du contenu avec des balises comme <h1> pour un titre, <p> pour un paragraphe, <ul> pour une liste et <table> pour un tableau. Cet outil transforme chaque structure RST en la balise HTML de même sens ; les encadrés et les blocs de code reçoivent des noms de classe pour qu'une feuille de style puisse s'y attacher. La sortie n'a pas d'apparence propre (CSS), seulement une structure : collée dans un billet de blog ou un système de gestion de contenu, elle prend d'elle-même le style de cette page. Le HTML brut et les adresses javascript: ne sont volontairement pas transmis.

Quelle est la différence entre RST et Markdown ?

Les deux mettent en forme du texte brut, mais ils appartiennent à des mondes différents. Markdown est court et souple : # titre, **gras**, [lien](adresse) ; GitHub, les forums et les applications de notes l'utilisent, il a de nombreux dialectes, et les tableaux ou les encadrés ne font pas partie du standard. reStructuredText est plus strict et plus riche : les titres sont soulignés, les directives (.. note::, .. code-block::) et les rôles (:sup:, :ref:) rendent le document extensible, les tableaux et les notes de bas de page font partie du standard — c'est pourquoi la documentation Python et Sphinx le préfèrent. L'un se convertit automatiquement en l'autre, mais pas un pour un : la plupart des structures Markdown ont un équivalent RST, les directives RST n'en ont pas en Markdown.

Quelles directives sont converties, lesquelles sont ignorées ?

La force du RST, ce sont ses directives (blocs commençant par .. nom::), et certaines n'ont de sens qu'à l'intérieur de Sphinx. Cet outil convertit les directives qui produisent du contenu : image et figure deviennent des éléments image, code-block / code / sourcecode un bloc de code avec une classe de langage, et note / warning / tip / important / caution / danger / hint / attention / error un encadré dont le titre est écrit dans la langue de la page.

Les directives qui relèvent du processus de construction plutôt que du document — toctree, contents, include, math, csv-table, list-table — ne produisent aucun HTML ; leur corps ne fuit pas dans la sortie et la ligne de résultat les compte comme « N directives non prises en charge ignorées », ce qui vous signale une section manquante sans parcourir la sortie. .. raw:: html n'est volontairement pas pris en charge : aucun HTML brut ne peut être injecté dans une page à partir d'une entrée RST.

Pourquoi la sortie ne « ressemble » pas à une page

Ce que vous voyez dans le panneau de droite est du code HTML, pas une page mise en forme : les balises sont écrites en clair. C'est voulu : le travail de l'outil est de rendre le texte transportable. Pour voir le résultat, choisissez « Page complète », téléchargez le fichier .html et ouvrez-le d'un double clic ; le navigateur l'affiche comme n'importe quelle page.

La sortie ne contient aucun style (CSS) ; les encadrés portent la classe admonition et les blocs de code des classes comme language-python, pour que vous puissiez brancher votre propre feuille de style. Dans les liens, seules les adresses http(s), mailto, tel et relatives sont conservées ; les adresses javascript: et data: sont remplacées par #.

• Fragment HTML → à coller dans un billet de blog, un éditeur de CMS ou une page existante
• Page complète → à enregistrer comme fichier et ouvrir dans le navigateur, à joindre à un e-mail
• Si votre source est en Markdown → utilisez l'outil Markdown vers HTML ; les deux syntaxes ne se mélangent pas

Questions fréquentes

Comment convertir un fichier RST en HTML ?

Ouvrez le fichier .rst dans un éditeur de texte, copiez son contenu et collez-le dans le panneau de gauche ; le HTML est produit aussitôt à droite. Pour l'enregistrer comme fichier, choisissez « Page complète » et appuyez sur Télécharger. Le texte ne quitte pas votre appareil : la conversion se fait dans le navigateur.

Pourquoi les directives Sphinx comme toctree ou autodoc manquent-elles dans la sortie ?

Ce ne sont pas du contenu mais des emplacements que Sphinx remplit depuis d'autres fichiers au moment de la construction ; on ne peut pas les produire à partir d'un seul texte. L'outil les ignore et la ligne de résultat indique combien de directives ont été ignorées. Les directives de contenu — titres, listes, tableaux, blocs de code et encadrés — sont converties intégralement.

Pourquoi les niveaux de titre ne sont-ils pas ceux que j'attendais ?

En RST, aucun caractère n'est lié à un niveau fixe ; comme docutils, cet outil attribue les niveaux dans l'ordre où chaque style de soulignement apparaît pour la première fois dans le document. Un titre surligné compte comme un style différent du même caractère utilisé seulement en soulignement. Si le document commence par = puis utilise -, vous obtenez h1 puis h2.

Que se passe-t-il si je colle du Markdown ?

Les titres # et les liens [texte](adresse) de Markdown ne sont pas de la syntaxe RST ; ils ressortent en simples paragraphes et la ligne de résultat signale qu'aucune structure n'a été trouvée. Pour le Markdown, utilisez l'outil Markdown vers HTML. Le RST se reconnaît facilement aux lignes ===== ou ----- sous les titres et aux lignes de directive commençant par ..