Ruby/Annexe/Créer une documentation


Dans ce chapitre, nous utiliserons la console pour créer une documentation, ce qui est quand même plus efficace que si nous le faisions manuellement.

Créer une documentation
Image logo représentative de la faculté
Annexe 3
Leçon : Ruby

Annexe de niveau 14.

Précédent :Mots-clés
Suivant :Sommaire
En raison de limitations techniques, la typographie souhaitable du titre, « Annexe : Créer une documentation
Ruby/Annexe/Créer une documentation
 », n'a pu être restituée correctement ci-dessus.




Principe de fonctionnement

modifier

Vous souhaitez que n’importe qui puisse comprendre le fonctionnement de votre programme, de vos classes, méthodes, etc. ? La meilleure solution est de créer une documentation. C'est-à-dire un ensemble de fichiers HTML, pouvant être consultés en ligne ou non, détaillant le fonctionnement de votre code. Pour cela, il faut que vous commentiez votre code (en français et/ou anglais si possible).


Assurez-vous que rdoc est installé sur votre machine (pour Windows : il est présent dans l'installateur, pour Linux : dans les dépôts). Lorsque vous exécutez rdoc, vous pouvez lui passer la liste des fichiers à documenter :


rdoc [fichier1] [fichier2] [etc.]


Si vous ne lui en passez aucun, il génère la documentation pour tous les fichiers du répertoire courant.


Cela a eu pour conséquence de créer un dossier /doc/ dans votre répertoire, qui contient vos fichiers HTML dont l'architecture est la suivante : les fichiers, classes et méthodes sont listés en haut, le détail du code apparaît au centre (avec vos commentaires).


Les commentaires peuvent s'appliquer à ce que vous voulez : une classe en général, mais pourquoi pas à une méthode particulière. Vous pouvez créer une documentation pour ce code et voir par vous-mêmes les différents emplacements possibles pour les commentaires :

Début de l'exemple
Fin de l'exemple


Mettre en forme la documentation

modifier

Il existe différents moyens d'améliorer la lisibilité des pages.

Modifier la typographie

modifier

Il vous est par exemple possible de modifier la typographie à certains endroits du texte : mettre des parties en gras, en italique ou d’utiliser une police à taille fixe (l'équivalent de la balise <pre> en HTML).

La procédure n’est pas la même pour les groupes de mots que pour les mots isolés, voici comment procéder :

Pour des mots isolés

modifier
Début de l'exemple
Fin de l'exemple


Pour des groupes de mots

modifier
Début de l'exemple
Fin de l'exemple


Hiérarchiser la documentation

modifier

Afin de mieux hiérarchiser votre document, il est également possible de placer des titres et des sous-titres.

6 niveaux existent, les titres les plus importants sont précédés d'un =, les moins importants de ======.

Cette hiérarchie suit le même ordre que celle établie en HTML (de <h1> à <h6>) :

Début de l'exemple
Fin de l'exemple


Créer des listes

modifier

Vous pouvez placer des listes au sein de votre code. En voici quelques exemples.

Listes à puces

modifier
Début de l'exemple
Fin de l'exemple


Listes ordonnées

modifier
Début de l'exemple
Fin de l'exemple


Listes de définition

modifier
Début de l'exemple
Fin de l'exemple


Tableaux

modifier
Début de l'exemple
Fin de l'exemple


Sachez également qu’à l'intérieur de la documentation, à chaque fois que vous mentionnez une classe, un fichier ou une méthode, cette référence devient un lien pointant vers cette destination. De plus, les URL sont automatiquement converties en lien.

Si vous voulez qu'une classe ou une méthode ne soit pas documentée, c’est très simple, il vous faut la commenter de cette manière :

Début de l'exemple
Fin de l'exemple


Ainsi, le code en question ne sera pas répertorié dans la documentation.