Aller au contenu

Ruby/Annexe/Créer une documentation

Leçons de niveau 14
Une page de Wikiversité, la communauté pédagogique libre.
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.




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.


Principe de fonctionnement

[modifier | modifier le wikicode]

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 | modifier le wikicode]

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

Modifier la typographie

[modifier | modifier le wikicode]

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 | modifier le wikicode]
Début de l'exemple
Fin de l'exemple


Pour des groupes de mots

[modifier | modifier le wikicode]
Début de l'exemple
Fin de l'exemple


Hiérarchiser la documentation

[modifier | modifier le wikicode]

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 | modifier le wikicode]

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

Listes à puces

[modifier | modifier le wikicode]
Début de l'exemple
Fin de l'exemple


Listes ordonnées

[modifier | modifier le wikicode]
Début de l'exemple
Fin de l'exemple


Listes de définition

[modifier | modifier le wikicode]
Début de l'exemple
Fin de l'exemple


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.