Avant de commencer

Si vous ne l'avez pas déjà fait, nous vous invitons à installer l'ensemble des outils tiers utilisés par AdeliaDoc.

L'installation de ces outils est requise pour le bon fonctionnement du générateur de documentation.

Dans la suite de ce tutoriel, nous allons travailler sur un projet de documentation :

• en langue anglaise (langue standard du produit avec le français),
• qui sera situé dans le répertoire c:\Test\AdeliaDocProject,
• et qui sera constitué de deux programmes Visual Adélia batch ADEL_DOC1 (accompagné de la procédure PROC1) et ADEL_DOC2, et d'une classe ADEL_CLASS1.

Les deux programmes et la classe n'ont pour objet que d'illustrer les fonctionnalités d'AdeliaDoc, ils ne contiendront de ce fait que le code minimum nécessaire à la production de la documentation.

Vous trouverez ci-dessous le code de base de ces trois entités, que vous pourrez copier dans votre environnement de test.

L'ensemble des commandes AdeliaDoc sont passées depuis l'invite de commande Windows® (⊞Win-r et saisir "cmd").

Si le répertoire d'installation d'Adélia Studio ne figure pas dans la variable d'environnement PATH de votre session Windows®, positionnez vous dans le répertoire Adélia Studio ("C:\Program Files (x86)\Adelia Studio" par défaut) avant d'exécuter les commandes AdeliaDoc.

Etape 1 : Initialisation du projet de documentation

• les fichiers de configuration initialisés avec les valeurs par défaut,
• les fichiers de commandes nécessaires à l'appel de Sphinx,
• ainsi que les différentes ressources liées.

• le répertoire où sera situé le projet (obligatoire) ,
• un code langue (obligatoire), qui sera de facto le code langue de la documentation - la liste des codes langues supportés est la liste des codes langues proposée par Sphinx,
• il est aussi possible de passer en paramètre le titre de projet de documentation.
  Ce paramètre est facultatif ; nous verrons dans la prochaine étape comment personnaliser le projet de documentation, en modifiant, entre autres, le titre par défaut fixé par AdeliaDoc.

Commande d'initialisation du projet de documentation exemple :

c:\Test>adeliadoc -ACTION:init -lang:en -project:"c:\Test\AdeliaDocProject" -log:c:\temp\adeliadoc.log

• si tout s'est bien passé, l'intitulé "L'opération a réussi" s'affiche en vert à l'écran :
  • c'est dans les sous-répertoires "classes" et "programs" du sous-répertoire "source" que seront produits les fichiers markup source générés par AdeliaDoc à partir de l'analyse des programmes L4G.
  • le sous-répertoire "build" contiendra pour sa part les supports de documentation construits par Sphinx, à partir du traitement des fichiers markup source.
• en cas d'erreur, l'intitulé "L'opération a échoué" s'affiche en rouge à l'écran, avec le message d'erreur explicatif.

Etape 2 : Personnalisation du projet 

Après avoir initialisé un projet, il est généralement souhaitable de modifier le paramétrage standard afin de personnaliser à minima le contenu des éléments communs constitutifs de la documentation, et notamment la page principale (c'est-à-dire la page d'accueil dans le cas d'une documentation au format HTML).

Dans ce tutoriel, nous vous proposons :

• de modifier les intitulés figurant dans le fichier markup source correspondant à la page principale  : fichier "index.rst";
• de modifier les informations générales du projet dans le fichier de configuration de Sphinx  : fichier "conf.py".

Pour cela, vous devez ouvrir ces deux fichiers dans un éditeur qui supporte l'encodage UTF-8 (Notepad++ par exemple), qui est l'encodage de tous les fichiers manipulés par AdeliaDoc. Il faudra bien sûr veiller à enregistrer vos modifications dans cet encodage.

Modification du fichier "index.rst"

• Le but est de changer le titre du projet, en remplaçant l'intitulé "Welcome to Adelia API documentation!" par, par exemple, "My first AdeliaDoc documentation Project".
  • Ce fichier est de type textuel, mais utilise la syntaxe de markup reStructuredText pour la définition de la mise en forme.
  • C'est pour cette raison, mais aussi parce que la longueur du nouveau titre est supérieure au titre par défaut, qu'il faut agrandir la ligne de caractères "==" qui se trouve juste sous le nouveau titre.
    Cette ligne permet de matérialiser le titre d'une section dans la page.
• Une fois la modification effectuée, enregistrez le fichier.
• Ce fichier peut bien sûr être plus largement personnalisé - pour plus de détails, reportez vous à la page d'aide dédiée aux personnalisations de la page d'accueil.

Modification du fichier "conf.py"

• Le but est de changer les informations générales du projet, à savoir le nom du projet et sa version :
  • Pour le nom du projet, repérez le paramètre nommé "project", et affectez lui la valeur "My doc project" à la place de "Adelia API".
  • Pour la version, repérez le paramètre nommé "release", et affectez lui la valeur "2.0" à la place de "1.0".
• Une fois la modification effectuée, enregistrez le fichier.
• Ce fichier peut bien sûr être plus largement personnalisé - pour plus d'informations, reportez vous à la page d'aide dédiée aux personnalisations de la configuration Sphinx.

Etape 3 : Génération de la documentation par défaut au format HTML

Pour rappel, AdeliaDoc permet de générer de la documentation technique associée aux programmes Adélia à partir :

• de l'analyse des sources L4G,
• de l'exploitation des informations de description des programmes,
• d'annotations spécifiques, sous forme de commentaire, qui ont été ajoutées au source L4G par les développeurs.

• le répertoire où sera situé le projet (obligatoire),
• l'environnement Adélia où se trouvent les sources - dans notre cas il se nomme "TEST_ENV",
• le format souhaité pour la documentation (HTML dans notre cas),
• de manière optionnelle, il est possible de restreindre la liste des programmes qui constitueront la documentation, en sachant que, par défaut, si rien n'est précisé, la documentation générée porte sur l'ensemble du référentiel de l'environnement passé en paramètre. Dans notre cas, comme nous souhaitons simplement créer une documentation qui porte sur deux programmes, nous allons utiliser le paramètre optionnel ad hoc nommé pgm.

Commande de génération du projet de documentation exemple :

c:\Test>adeliadoc -ACTION:generate -project:"c:\Test\AdeliaDocProject" -env:TEST_ENV -format:HTML -pgm:ADEL_DOC1;ADEL_DOC2 -log:c:\temp\adeliadoc.log

• Si tout s'est bien passé, l'intitulé "L'opération a réussi" s'affiche en vert à l'écran :

  • Il est possible que vous obteniez des avertissements - n'y prêtez pas attention dans le cadre de ce tutoriel.

  • La page principale de la documentation générée est "C:\Test\AdeliaDocProject\build\html\index.html"

  • Les sections d'aide relatives à nos deux programmes ont bien été générées avec des valeurs par défaut, y compris la procédure "PROC1" de "ADEL_DOC1".

  • Etant donné qu'un des paramètres du programme "ADEL_DOC1" référence une classe, la classe correspondante est automatiquement générée par AdeliaDoc, et un lien hypertexte permet d'y accéder directement depuis la page d'aide de ce programme. Par ailleurs vous noterez que les déclarations *SER_DESC positionnées sur la déclaration et un attribut de la classe, ont bien été reconduites dans la documentation.

  • enfin, vous noterez également que les personnalisation effectuées à l'étape 2 ont bien été prises en compte.

• En cas d'erreur, l'intitulé "L'opération a échoué" s'affiche en rouge à l'écran, avec le message d'erreur explicatif. Consultez le fichier log pour plus de détails.

Etape 4 : Ajout d'annotations dans les sources L4G

A présent que nous disposons d'une documentation de base, nous allons ajouter des annotations dans les sources L4G afin d'auto-documenter les programmes.
Les annotations disponibles permettent de couvrir l'essentiel des besoins d'une documentation technique.
Dans le cadre de ce tutoriel, nous nous limiterons à quelques unes d'entre elles. 

Pour insérer les annotations dans les programmes, il suffit de copier le code des annotations fourni ci-dessous avant l'ordre PARAM des programmes/procédure correspondantes. En pratique, il est bien sûr possible de structurer différemment les choses, le tout étant que les annotations figurent toutes avant l'ordre PARAM.

Ajout d'annotations dans le programme ADEL_DOC1

Les modification consistent :

• pour le programme lui-même :
  • à ajouter une annotation de description de programme qui inclus de la mise en forme de texte et un lien vers le programme ADEL_DOC2,
  • à ajouter une annotation de description du paramètre liste LST (et de deux de ses champs) et du paramètre DT1,
  • à ajouter une annotation d'index avec deux entrées.
• pour la procédure PROC1 :
  •  à ajouter une annotation de dépréciation. 

Ajout d'annotations dans le programme ADEL_DOC2

La modification consiste à ajouter deux annotations d'index hiérarchique - dont une pour laquelle le père a déjà été créé (cf. ADEL_DOC1 ), la seconde, non.

Etape 5 : Prise en compte de l'ajout des annotations

Après avoir enregistré les programmes, relancez la génération.

Commande de génération du projet de documentation exemple :

c:\Test>adeliadoc -ACTION:generate -project:"c:\Test\AdeliaDocProject" -env:TEST_ENV -format:HTML -pgm:ADEL_DOC1;ADEL_DOC2 -log:c:\temp\adeliadoc.log

• Si tout s'est bien passé, l'intitulé "L'opération a réussi" s'affiche en vert à l'écran, et vous pouvez constater que les annotations insérées ont bien été retranscrites dans la nouvelle version de la documentation :

  • les descriptions du programme et des paramètres de ADEL_DOC1, avec la mise en forme (gras) et les liens hypertexte,

  • le commentaire de dépréciation sur la procédure,

  • la page d'index, avec nos différentes entrées, hiérarchiques ou simples (voir l'étape suivante pour une utilisation avancée de la page d'index) du programme ADEL_DOC2.

• En cas d'erreur, l'intitulé "L'opération a échoué" s'affiche en rouge à l'écran, avec le message d'erreur explicatif. Consultez le fichier log pour plus de détails.

Etape 6 : Paramétrage avancé

En standard, AdeliaDoc applique des règles de génération par défaut, qui peuvent ne pas toujours être en adéquation avec vos besoins.

C'est pourquoi, projet par projet, il est possible de modifier le comportement par défaut d'AdeliaDoc en surchargeant certaines règles de génération. C'est la fonction du fichier de configuration "adeliadoc.ini".

Dans le cadre de ce tutoriel, nous nous limiterons à la modification des règles de génération des index, et de l'exclusion de l'annotation *@author.

Pour une vue complète sur les possibilités de paramétrage avancé, nous vous invitons à consulter la rubrique d'aide sur le fichier de configuration adeliadoc.ini.

Edition du fichier "adeliadoc.ini"

Le fichier de configuration est encodé en UTF-8 sans BOM.

Il est donc nécessaire d'utiliser un éditeur adapté (Notepad++ par exemple)

Modification des règles de génération des index

En standard, et en plus des index associés aux annotations *@index ajoutées dans les sources L4G, AdeliaDoc génère autant d'entrées d'index que de programmes et de procédures documentées. Chaque entrée d'index portant le nom de l'entité correspondante.

Ce comportement n'est pas toujours adapté aux différentes typologies de documentation, et notamment dans notre projet de test, où nous avons pris le parti de gérer explicitement et exhaustivement les entrées d'index via l'annotation *@index.

C'est pour cela que nous allons modifier le paramètre index_generation , en lui affectant la valeur "annotation", pour signifier à AdeliaDoc de ne pas générer les entrées d'index implicites basées sur les noms de section : 

index_generation = annotation

Comme vous pouvez le constater en consultant la documentation, le paramétrage disponible permet de configurer assez finement le comportement relatif à la génération des index. 

Exclusion des annotations *@author

Dans certaines situations, il peut être intéressant de ne pas faire figurer dans la documentation les informations associées à certaines annotations, même si celles-ci sont explicitement présentes dans un source L4G. Cela peut par exemple être le cas du nom des développeurs dans une documentation publique.

Le paramètre exclude_annotations est fait pour cela. Il suffit de valoriser ce paramètre de la manière suivante : 

exclude_annotations = *@author

Remarque sur la régénération de la documentation

A ce stade, nous avons simplement modifié le fichier de configuration AdeliaDoc, sans nouvelle modification de sources L4G depuis la dernière génération.

Le processus incrémental de construction d'AdeliaDoc devrait donc inhiber la régénération de la documentation, puisque qu'il n'y a eu aucune modification de source. Cependant, du fait que ces modifications de paramétrage ont une incidente directe sur le contenu des informations restituées dans la documentation (nouvelle version de la page d'index et suppression du nom des développeurs dans notre exemple), AdeliaDoc va être en mesure de détecter ces évolutions de paramètre de façon à basculer en mode génération forcé.

Plus largement, AdeliaDoc désactive la génération incrémentale lorsque toutes les conditions contextuelles ne sont pas réunies, et ce en se basant sur un cache de données associé au projet de documentation.

Commande de génération du projet de documentation exemple :

c:\Test>adeliadoc -ACTION:generate -project:"c:\Test\AdeliaDocProject" -env:TEST_ENV -format:HTML -pgm:ADEL_DOC1;ADEL_DOC2 -log:c:\temp\adeliadoc.log

• Si tout s'est bien passé, l'intitulé "L'opération a réussi" s'affiche en vert à l'écran :

  • Vous noterez l'affichage à l'écran de messages d'avertissement indiquant qu'AdeliaDoc a forcé un mode de génération complet.

  • Dans la documentation regénérée, les informations liées aux auteurs de section ont disparu.

  • La page d'index ne contient plus que les entrées correspondant aux annotations insérées.

• En cas d'erreur, l'intitulé "L'opération a échoué" s'affiche en rouge à l'écran, avec le message d'erreur explicatif. Consultez le fichier log pour plus de détails.

Etape 7 : Génération de la documentation au format TEXTE

Après avoir regénéré la documentation au format HTML, vous pourriez souhaiter décliner votre support de documentation dans un des autres formats supportés, par exemple un format purement textuel.

Dans ce cas, et plutôt que de relancer un processus complet de génération, il est plus simple et plus rapide de relancer juste une construction Sphinx de la documentation, dans le nouveau format cible.

L'action make est précisément adaptée à ce cas de figure : elle consiste à exécuter uniquement la production du support de documentation par un appel à Sphinx, en repartant des fichiers markup sources générés par AdeliaDoc.
Cette action nécessite de passer en paramètres :

• le répertoire où est situé le projet (obligatoire),
• le format souhaité (obligatoire).

Commande de génération du projet de documentation exemple :

c:\Test>adeliadoc -ACTION:make -project:"c:\Test\AdeliaDocProject" -format:TEXT -log:c:\temp\adeliadoc.log

• Si tout s'est bien passé, l'intitulé "L'opération a réussi" s'affiche en vert à l'écran. Les fichiers textuels générés se trouvent sous "C:\Test\AdeliaDocProject\build\text".

• En cas d'erreur, l'intitulé "L'opération a échoué" s'affiche en rouge à l'écran, avec le message d'erreur explicatif.