TP - Programmation Python pour la BIOInfo

La structure de la documentation est définie par pages où chaque page est définie par un fichier .rst

Le fichier index.rst est un fichier spécial qui contient la page d'accueil qui contient le menu principal de navigation.

Le fichier de base généré par sphinx ressemble a ceci  :

Il contient déjà un certain nombre de balises notament les titres de parties, les listes et le TOCTree.

Les titres de parties et de sous partie sont défini a l'aide d'un soulignage a l'aide des caractères suivants : '=','-','*',...

Pour créer un titre, il suffit donc de l'écrire et de le souligner avec l'un des caractère ci-dessous de façon à ce que la ligne de soulignage soit au moins aussi longue que le titre.

Alterner les caractères permet ainsi de définir des différents niveaux.

Pour construire des liste, il suffit simplement de faire débuter chaque ligne par le caractère '*', '+' ou '-' (pour des listes non ordonnées) ou 1,2,3... pour des listes ordonnées.

Tous les titres sont concidérés comme des liens et peuvent être désignés par l'instruction :

Vous pouvez également créer des ancres par l'instruction

Et créer des liens ver elle avec l'instruction monAncre_.

Le TocTree ou Table Of Content Tree est ce qui servira de table des matière pour votre documentation.

Pour l'instant il est vide, nous allons donc y ajouter des pages.

Créons par exemple dans le même dossier que index.rst, les fichiers page1.rst, page2.rst.

Dans chacune de ces pages créeons simplement un titre et un sous-titre

page1.rst

page2.rst

Nous allons ensuite ajouter ces pages au contenu de notre site et les référencer dans le TOCTree principal.

Pour cela il suffit d'ajouter le nom des pages a la suite de l'instruction toctree.

A la génération de votre documentation, vous verez apparaitre dans votre menu des liens vers les parties et sous parties des 2 pages.

TocTree

Ici les sous-parties sont également visibles puisque l'attribut :maxdepth: est fixé à 2 ce qui inclut donc les titres et sous-titre. Si vous souhaitez afficher uniquement la liste des titres. Fixez cette valeur à 1.

Sphinx offre des instructions, qui s'ajoutent a celle de ReStructured Text et qui vont nous permettre la génération automatique de la documentation a partir des commentaires.

Prenons ce module python myModule.py :

Il contient des fonctions d'affichages dont j'aimerais faire la documentation dans le fichier que j'ai appelé page2.rst.

Pour cela on ajoute dans le fichier l'instruction suivante : .. automodule:: myModule

Cette instruction permet d'ajouter à la documentation toute l'information contenue dans le commentaire général du module (les commentaires situés sur les premières lignes du module)

Documentation générale

Mais cela peut ne pas être suffisant et l'on souhaiterait pouvoir ajouter a cela la liste des fonctions avec leur documentation propre.

Pour cela, il faut ajouter sur la ligne suivant .. automodule:: myModule la commande :members: (avec une indentation). Elle permet à Sphinx de comprendre que vous souhaitez incorporer ici la documentation de tous les membres du module.

Documentation des membres

Pour une meilleure lisibilité et afficher la paternité de votre module, je vous recommande de faire figurer les information d'auteur et de date de création en début de module.

Pour cela vous pouvez utiliser les balises :Author: et :Date:.

Métadonnées

Vous pouvez compléter ces champs par d'autres comme :Version:, :Description: ou tout autre information que vous jugerez utile (entre deux ':').

Si vous avez choisi d'activer l'extension todo de sphinx, vous avez accès à deux instruction supplémentaires : .. todo:: et .. todolist::

Vous pouvez ajouter a un endroit du code ou il vous reste quelque chose a faire l'instruction .. todo ::

Ensuite, en utilisant l'instruction .. todolist::, vous afficherez la liste complète des choses qu'il vous reste a faire dans le programme avec un lien vers leur emplacement.

TODOList