Amélioration de la documentation d'atoum grâce à Rusty

Introduction

La documentation d’atoum contient de nombreux exemples de code en PHP.

Parfois, ceux-ci ne fonctionnaient pas : ces exemples contenaient des erreurs de syntaxe.

Par exemple, comme ci-dessous, il manquait un point virgule à la fin d’une ligne : un utilisateur copiant ces lignes n’avait donc pas directement un exemple fonctionnel.

``length`` allows you to get an asserter of type integer that contains the string's size.

.. code-block:: php

  <?php
   $string = 'atoum'

   $this
       ->string($string)
           ->length
               ->isGreaterThanOrEqualTo(5)
   ;

Nous verrons comment nous avons supprimé ces erreurs en utilisant Rusty.

Rusty

Rusty est un outil écrit en PHP par Kevin Gomez, permettant d’extraire des blocs de code depuis de la PHPDoc ou du markdown, et de les exécuter ou valider (l’auteur a d’ailleurs écrit un article pour le présenter).

Utilisation dans atoum

Support du format RST

La documentation d’atoum utilise sphinx (elle est hébergée sur ReadTheDocs). Le format utilisé est donc du RST.

Rusty supportait le format Markdown, mais pas le RST. Heureusement, les mécanismes étaient déjà en place dans Rusty pour ajouter de nouveaux formats. Nous avons donc effectué une Pull Request pour ajouter le support du format RST (en s’appuyant sur la librairie gregwar/rst).

Correction des erreurs

Rusty se lance de cette façon :

./vendor/bin/rusty check --no-execute source/ -v

Nous allons ici lancer rusty sans executer le contenu des blocs trouvés (en validant seulement leur contenu) dans les fichiers du dossier “source”, avec un affichage détaillé sur la sortie.

Le résultat d’une telle commande donne une sortie comme celle-ci :

⚑ Analysing file source/en/first_test.rst
 → Found code sample in line 0
 ✘ Syntax error in source/en/first_test.rst:0

```
namespace Vendor\Project;

class HelloWorld
{
    public function getHiAtoum ()
    {
        return 'Hi atoum !'
    }
}
```

  [Rusty\Lint\Exception\SyntaxError]
  Syntax error in code sample "

  namespace Vendor\Project;
  class HelloWorld
  {
    public function getHiAtoum ()
    {
      return 'Hi atoum !'
    }
  }" in /sources/source/en/first_test.rst:0 → Syntax error, unexpected '}', expecting ';' on line 10

Sur cette sortie nous pouvons voir que Rusty :

• va parcourir les différents fichiers supportés (php, markdown, et RST);
• va chercher des exemples de code php dans la documentation markdown ou RST, ou dans la PHPDoc;
• s’il trouve des exemples, il va linter ceux-ci : vérifier que leur syntaxe est correcte;
• en cas d’erreur, l’exemple en question sera affiché, ainsi que l’erreur remontée.

Sur la documentation d’atoum, Rusty, nous a permis, dans un premier temps, de détecter et corriger de nombreuses erreurs (comme vous pouvez le voir dans cette Pull Request).

Automatisation des vérifications

Corriger ces erreurs est une bonne chose. Éviter qu’elles apparaissent à nouveau c’est encore mieux. Pour cela nous avons ajouté une configuration travis sur le dépot de documentation, afin que les développeurs soient prévenus de ce genre d’erreur via le statut des pull requests.

Dans cette Pull Request, vous pouvez voir un exemple de mise en place de rusty sur travis.

Conclusion

La documentation est un point essentiel dans l’adoption d’un projet, et des exemples non fonctionnels peuvent faire la différence dans le choix d’une librairie. Mettre en place Rusty se fait très simplement et améliorera l’expérience de vos utilisateurs.