Formatter automatiquement la documentation RestructuredText (RST)

Pour vérifier l’écriture de fichiers RST, il est possible d’utiliser des linters

restructuredtext-lint qui ne permet que de vérifier la syntaxe RST, mais donc permet d’afficher les erreurs de syntaxe RST directement dans l’éditeur de code.

rstfmt qui permet de vérifier la syntaxe RST de sphinx ET de formatter automatiquement le code RST.

docstrfmt est un fork récent à surveiller.

restructuredtext-lint

Installation de restructuredtext-lint

Activer l’environnement virtuel et installer le linter avec la commande suivante depuis le dossier sphinx du projet:

cd ~/info_indus/info_indus_tutorial/doc/sphinx
source .venv/bin/activate
pip install restructuredtext-lint

Utilisation de restructuredtext-lint

Pour vérifier un fichier RST (dont le nom est bad_format_rst_file.rst), il suffit de lancer la commande suivante:

rst-lint bad_format_rst_file.rst

Si le fichier contient le code rst ci-dessous:

.. code-block:: python
   import math as m
   print(m.pi)

Le linter renvoie les erreurs suivantes:

ERROR bad_format_rst_file.rst:1 Error in "code-block" directive:
maximum 1 argument(s) allowed, 6 supplied.

Explications

Il manque, par exemple, un saut de ligne après la directive .. code-block et la ligne python import math as m est comprise comme un paramètre de la directive code-block et est donc mal interprétée.

rstfmt

Installation de rstfmt

Activer l’environnement virtuel et installer le linter avec la commande suivante depuis le dossier sphinx du projet:

cd ~/info_indus/info_indus_tutorial/doc/sphinx
source .venv/bin/activate
pip install rstfmt

Utilisation de rstfmt en ligne de commande

Pour visualiser les erreurs de formatage d’un fichier RST (dont le nom est bad_format_rst_file.rst), il suffit de lancer la commande suivante:

rstfmt --diff <file>

Le résultat apparaîtra dans le terminal sous le format d’un fichier diff (comme avec git). Pour sauvegarder le résultat dans un fichier, il suffit de rediriger la sortie standard vers un fichier:

rstfmt --diff <file> > <output_file>

Pour formatter un fichier RST en place (dont le nom est bad_format_rst_file.rst), il suffit de lancer la commande suivante:

rstfmt bad_format_rst_file.rst

ATTENTION: le fichier est modifié directement.

Utilisation dans l’éditeur de code

Visualisation directe

Il est possible d’utiliser le linter directement dans l’éditeur de code. Par exemple, dans vscode, il est possible d’installer l’extension reStructuredText qui permet de vérifier la syntaxe RST directement dans l’éditeur.

Les erreurs sont alors affichées directement dans l’éditeur de code qui souligne les erreurs avec des vagues comme dans l’image ci-dessous:

En passant la souris sur la partie soulignée, une bulle d’information apparaît avec le message d’erreur et de la documentation sur la commande utilisée. L’erreur rapportée n’est pas toujours pertinente, et il est souvent très instructif de parcourir la documentation et en particulier de scruter les exemples fournis.

La limite de cette visualisation c’est qu’il faut avoir le fichier ouvert à l’emplacement d’une erreur dans l’éditeur pour voir l’erreur.

Visualisation minimap

Les erreurs apparaissent également comme des lignes en rouge dans la vue latérale minimap de vscode qui donne une vue d’ensemble du fichier. On peut activer cette vue en faisant un clic droit sur la barre de scrolling du fichier (à droite) et en checkant Minimap.

Visualisation dans la vue `Problems`

Les erreurs sont également listées dans la vue Problems de vscode. On peut y accéder

en cliquant sur l’icône en forme de triangle dans la barre de status de vscode souvent située en bas à gauche de la fenêtre.

en ouvrant la vue de terminal en bas et sélectionnant l’onglet Problems.

C’est la vue la plus intéressante car toutes les erreurs de tous les fichiers sont listées, avec un lien clickable pour se rendre directement à l’endroit de l’erreur dans le fichier.