Généralités
L'outil AdeliaDoc permet de gérer l'ensemble du cycle de vie d 'un projet de documentation technique Adélia , à savoir :
- L'initialisation d'un projet de documentation, configuré avec les paramètres par défaut.
- La génération des fichiers markup source (.rst) à partir de l'analyse des sources L4G et de l'exploitation des informations de description des programmes.
- La production de la documentation dans le format attendu, à partir des fichiers markup source.
- La suppression de l'ensemble des éléments issus de la génération, avec conservation des paramètres de configuration personnalisés ainsi que du paramétrage Sphinx.
- La suppression d'un projet de documentation.
Dans ce cadre, les paramètres d'appel d'AdeliaDoc s'articulent autour d'un paramètre principal, dénommé action
, qui permet de déclencher l'exécution d'une des phases du cycle de vie décrites ci-dessus.
Associé à ce paramètre principal, on trouve un ensemble de paramètres secondaires (obligatoires ou optionnels), qui permettent de piloter les actions en question. Certains de ces paramètres secondaires étant communs à l'ensemble des actions.
Usage : adeliadoc -action:<nomAction> -project:<nomRepertoire> -lang:<codeLangue> -env:<codeEnvironnement> [-pgm:<listeProgrammes> | -app_area:<listeDomaines> | -build_comp:<ListeComposants>] -format:<codeFormat> [-filter:<listeFiltres>] [-title:<intituleProjet>] [-log[:<nomFichier>]] [-force]
Tableau descriptif des paramètres
Remarques préliminaires :
- la syntaxe de saisie des paramètres est :
-parametre[:valeur]
- dans le cas où une valeur de paramètre peut être constituée de plusieurs occurrences, les occurrences doivent être séparées par un point-virgule
- pour les paramètres dont la valeur peut contenir des blancs, celle-ci doit être encadrée par des guillements :
-param:"c:\temp\log file.txt"
- les paramètres et leurs valeurs ne sont pas sensibles à la casse
Nom | Description | Obligatoire |
action | oui | |
project | Répertoire racine du projet de documentation | oui |
env | Environnement Adélia de génération | non(1) |
app_area | Nom du/des domaines concernés par la génération | non |
build_comp
| Nom du/des composants de build concernés par la génération | non |
pgm | Nom du/des programmes concernés par la génération | non |
filter
| Filtre basé sur la présence et le contenu de l'annotation *@adeliadoc , permettant d'écarter certains programmes/procédures de la génération | non |
format | Format souhaité pour la documentation | oui(3) |
lang | Code langue du projet de documentation | non(2) |
title | Intitulé du projet de documentation | non |
force | Mode forcé, pour une génération complète de la documentation, en s'affranchissant du mode incrémental | non |
log | Chemin absolu du fichier log | non |
(1) sauf pour l'action generate
(2) sauf pour l'action init
(3) sauf pour les actions init|cleanup|delete
Description détaillée des paramètres
Ci-dessous la description détaillée de l'ensemble des paramètres d'appel supportés par AdeliaDoc.
Paramètre action
Description | Code de l'action à exécuter | ||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Obligatoire | Oui | ||||||||||||||||||||||||||||||||||||||
Valeurs | Prend une des valeurs suivantes :
|
Paramètre project
Description | Répertoire racine du projet de documentation (répertoire local au poste où s'exécute AdeliaDoc) |
---|---|
Valeur | Nom du répertoire |
Actions | |
Remarque | Veillez à ce que l'utilisateur Windows® exécutant AdeliaDoc ait bien les droits de lecture, d'écriture et de suppression sur le répertoire du projet. |
Exemple |
|
Paramètre env
Description | Nom canonique de l'environnement de génération Adélia |
---|---|
Valeur | Nom en question |
Action | generate : obligatoire |
Exemple |
|
Paramètre app_area
Description | Domaine(s) de l'environnement Adélia concernés par la génération de la documentation |
---|---|
Valeurs | Liste de noms de domaines, séparés par le caractère "; " |
Action | generate : facultatif |
Remarque | Exclusif avec les paramètres build_comp et pgm |
Exemple |
|
Paramètre build_comp
Description | Composant(s) de build de l'environnement Adélia concernés par la génération de la documentation |
---|---|
Valeurs | Liste de composants de build, séparés par le caractère "; " |
Action | generate : facultatif |
Remarque | Exclusif avec les paramètres app_area et pgm |
Exemple |
|
Paramètre pgm
Description | Programme(s) de l'environnement Adélia concernés par la génération de la documentation |
---|---|
Valeurs | Liste de noms de programmes, séparés par le caractère "; " |
Action | generate : facultatif |
Remarque | Exclusif avec les paramètres app_area et build_comp |
Exemple |
|
Paramètre filter
description | Filtre basé sur la présence et le contenu de l'annotation Si ce paramètre n'est pas renseigné, toutes les sections de la liste des programmes éligibles sont générées. |
---|---|
Valeurs |
|
Action | generate : facultatif |
Remarques |
|
Exemple |
|
Paramètre format
Description | Format souhaité pour la documentation |
---|---|
Valeurs |
|
Actions | |
Remarque | Si le format est positionné à la valeur RST , alors la génération AdeliaDoc se limite à la production des fichiers markup, sans production du support de documentation. |
Exemple |
|
Paramètre lang
Description | Langue de génération de la documentation |
---|---|
Valeur | AdeliaDoc supporte l'ensemble des langues supportées par Sphinx. La liste des langues est disponible ici. |
Action | init : obligatoire |
Remarque | Il est toujours possible de changer la langue d'un projet de documentation après l'avoir créé. Pour plus d'information, veuillez consulter la rubrique d'aide dédiée à la localisation. |
Exemple |
|
Paramètre title
Description | Intitulé du projet de documentation |
---|---|
Valeur | Intitulé en question |
Action | init : facultatif |
Remarque | Il est toujours possible de changer l'intitulé d'un projet de documentation après l'avoir créé. Pour plus d'information, veuillez consulter la rubrique d'aide consacrée à la personnalisation et configuration de Sphinx. |
Exemple |
|
Paramètre force
Description | Mode forcé , pour une génération complète de la documentation, en s'affranchissant du mode incrémental |
---|---|
Valeur | Aucune |
Action | generate : facultatif |
Remarque | Lorsque ce paramètre est positionné, l'action cleanup est automatiquement appelée avant l'exécution de l'action generate. |
Exemple |
|
Paramètre log
Description | Nom du fichier contenant le rapport d'exécution d'AdeliaDoc |
---|---|
Valeur | Nom absolu du fichier Si le nom du fichier n'est pas renseigné, par défaut, le rapport est créé dans le sous-répertoire " Attention : pour les actions init et delete , il est nécessaire de renseigner explicitement le nom absolu du fichier rapport. |
Actions | |
Remarque | Le rapport de génération contient l'ensemble des traces, messages (information/avertissement/erreur) et statistiques liés à l'exécution d'une action AdeliaDoc. Dans le cas de l'action generate, si ce paramètre n'est pas renseigné, une trace par défaut est générée dans l'éventualité où des erreurs et/ou avertissements seraient levés durant la génération de la documentation. Cette trace par défaut est localisée dans le sous-répertoire "log" du projet. Pour les autres actions, l'ensemble des messages sont redirigés vers la sortie standard ou la sortie erreur (console Windows® par défaut). |
Exemples |
|
Codes retour d'AdeliaDoc
Les valeurs de code retour renvoyés par AdeliaDoc.exe peuvent être classés en 3 catégories :
Exécution normale
- L'exécution s'est déroulée sans erreur et sans message d'avertissement : le code retour est alors positionné à la valeur "0".
Avertissements d'exécution
- Dans le cas où AdeliaDoc détecte des erreurs de syntaxe dans les annotations, ou bien si des différences sont détectées entre la définition des paramètres stockés en base de données par rapport à la déclaration des variables correspondantes dans le source L4G, le code retour est positionné à la valeur "1".
La totalité des messages d'avertissement sont consignés dans le fichier log par défaut, ou dans le fichier log indiqué en ligne de commande. - Dans le cas où au moins un des programmes ou classes à générer ne passent pas la vérification standard Adelia, le code retour est positionné à la valeur "2".
La totalité des messages d'avertissement sont consignés dans le fichier log par défaut, ou dans le fichier log indiqué en ligne de commande .
- Dans le cas où AdeliaDoc détecte des erreurs de syntaxe dans les annotations, ou bien si des différences sont détectées entre la définition des paramètres stockés en base de données par rapport à la déclaration des variables correspondantes dans le source L4G, le code retour est positionné à la valeur "1".
Erreurs d'exécution
- Un code retour dont la valeur est supérieure à "2" signifie que l'action demandée n'a pas pu aboutir.
Des informations complémentaires sur la nature et la raison de l'erreur sont alors consignées dans la sortie standard et dans le fichier log. - A titre d'information :
- le code "3" indique que la vérification Adélia standard a échoué pour l'ensembles des programmes éligibles.
- le code "4" indique qu'il n'y a aucun programme à générer.
- le code "5" signifie que les paramètres d'appels d'AdeliaDoc ne respectent pas la syntaxe attendue.
- Un code retour dont la valeur est supérieure à "2" signifie que l'action demandée n'a pas pu aboutir.