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`	Action à exécuter : `init\|generate\|make\|cleanup\|delete`	oui
`project`	Répertoire racine du projet de documentation	oui
`env`	Environnement Adélia de génération	non⁽¹⁾
`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⁽³⁾
`lang`	Code langue du projet de documentation	non⁽²⁾
`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

↑ Haut de page

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 :

init : initialisation d'un projet de documentation, dans le répertoire spécifié (paramètre project, pour le code langue indiqué (paramètre lang).
Le but de l'initialisation est de créer l'arborescence du projet de documentation, de générer les fichiers de configuration par défaut, les fichiers de commandes nécessaires à l'appel de Sphinx, ainsi que les différentes ressources liées.

Paramètres obligatoires	`lang`, `project`
Paramètres facultatifs	`log`, `title`
Remarque	Après la création du projet, les fichiers de configuration de Sphinx ainsi que le fichier de configuration AdeliaDoc peuvent être personnalisés afin de prendre en compte les spécificités du projet.
Exemple	`adeliadoc -action:init -lang:en -project:"d:\adeliaDoc\bdcadel\public"` `-title :"API Documentation V1"`

cleanup : suppression dans un projet de tous les fichiers générés par AdeliaDoc (fichiers html et pdf compris).
Les fichiers de configuration Sphinx et AdeliaDoc contenant les personnalisations de paramétrage sont quant à eux conservés.

Paramètre obligatoire	`project`
Paramètre facultatif	`log`
Exemple	`adeliadoc -action:cleanup -project:"d:\adeliaDoc\bdcadel\public"`

generate : génération des fichiers pivots et construction du support de documentation

Paramètres obligatoires	`project, env, format`
Paramètres facultatifs	`app_area`, `pgm`, `build_comp`, `filter`, `force`, `log`
Remarques	Si aucun des paramètres facultatifs `app_area`, `build_comp`, `pgm` n'est présent, la génération porte sur la totalité du référentiel. Par construction, l'action make est exécutée de façon automatique suite à la génération des fichiers pivots. Si les conditions le permettent, la génération est réalisée en mode incrémental. Ce qui signifie que seuls sont regénérés les fichiers markup source pour lesquels les programmes correspondants (ou/et leurs dépendances) ont été modifiés depuis la génération précédente.
Exemple	`adeliadoc -action: generate -env:bdcadel @hostame -project:"d:\adeliaDoc\bdcadel\public"` `-format:html -app_area:STOCK -filter:public;core`

make : permet de lancer uniquement la production du support de documentation, sur la base des fichiers markup (.rst) présents dans le sous-répertoire "source" du projet spécifié ( fichiers générés lors d'un précédant appel à AdeliaDoc , avec le paramètre action positionné à generate).
Cette action peut être utile dans certaines situations ( modification de thèmes d'apparence Sphinx, production d'une documentation dans un autre format à partir d'une même collection de fichiers markup , etc.).

Paramètres obligatoires	`project`, `format`
Paramètre facultatif	log
Remarque	Cette action ne tient pas compte d'éventuelles modifications apportées aux paramètres de configuration AdeliaDoc. Suite à une telle modification, il est impératif de lancer une génération complète (action generate). Comme pour l'action generate, le make est un processus incrémental. Sphinx ne régénère que les fragments de documentation pour lesquels des fichiers markup source ont été modifiés depuis la dernière génération.
Exemple	`adeliadoc -action:make -project:"d:\adeliaDoc\bdcadel\public" -format:pdf`

delete : suppression définitive d'un projet de documentation

Paramètre obligatoire	`project`
Paramètre facultatif	`log`
Remarque	Le contenu du répertoire associé au projet de documentation et le répertoire lui-même sont supprimés.
Exemple	`adeliadoc -action:delete -project:"d:\adeliaDoc\bdcadel\public"`

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	init : obligatoire generate : obligatoire make : obligatoire cleanup : obligatoire delete : obligatoire
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	`adeliadoc -action:make -env:bdcadel @prodsrv -project:"d:\adeliaDoc\bdcadel\public" -format:htm`

Paramètre env

Description	Nom canonique de l'environnement de génération Adélia
Valeur	Nom en question
Action	generate : obligatoire
Exemple	`adeliadoc -action:generate -env:bdcadel @prodsrv -project:"d:\adeliaDoc\bdcadel\public" -format:html`

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	`adeliadoc -action:generate -env:bdcadel @hostname -project:"d:\adeliaDoc\bdcadel\public" -format:html -app_area:STOCK`

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	`adeliadoc -action:generate -env:bdcadel@hostname -project:"d:\adeliaDoc\bdcadel\public" -format:html` `-build_comp:comp1;comp3`

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	`adeliadoc -action:generate -env:bdcadel@hostname -project:"d:\adeliaDoc\bdcadel\public" -format:html` `-pgm:programA;programC;programG`

Paramètre filter

description	Filtre basé sur la présence et le contenu de l'annotation `*@adeliadoc` et qui permet d'écarter certaines sections (i.e. programmes/procédures) de la génération de la documentation. Si ce paramètre n'est pas renseigné, toutes les sections de la liste des programmes éligibles sont générées.
Valeurs	Deux valeurs prédéfinies sont à disposition : ALL : toutes les sections contenant un `@adeliadoc`, (avec ou sans étiquette) sont éligibles. NONE : toutes les sections contenant un `@adeliadoc` vide (i.e. sans étiquette) sont éligibles. Ou bien un contenu libre basé sur une liste d'étiquettes séparées par le caractère "`;`" : dans ce cas, seules les sections ayant un `@adeliadoc` avec les étiquettes mentionnées sont éligibles (rappel : l'annotation `@adeliadoc` au niveau d'une section programme est héritée par défaut par toutes ses procédures publiques pour lesquelles cette annotation n'aurait pas été renseignée).
Action	generate : facultatif
Remarques	Les valeurs ALL et NONE sont exclusives. Par nature, la valeur *ALL ne peut être accompagnés d'aucun autre filtre. Il est possible de configurer un filtre par défaut au niveau des paramètres de configuration d'un projet. Le filtre par défaut s'applique lorsque ce paramètre de lancement n'est pas renseigné.
Exemple	`adeliadoc -action:generate -env:bdcadel@hostname -project:"d:\adeliaDoc\bdcadel\public" -format:html` `-filter:public;core;*NONE`

Paramètre format

Description	Format souhaité pour la documentation
Valeurs	HTML : documentation au format HTML PDF : document PDF LATEX: fichiers au format Latex TEXT : fichiers au format texte brut RST : fichiers pivots au format markup reStructuredText (`.rst`)
Actions	generate : obligatoire make : obligatoire
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	`adeliadoc -action:generate -env:bdcadel@hostname -project:"d:\adeliaDoc\bdcadel\public" -format:pdf`

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	`adeliadoc -action:init -project:"d:\adeliaDoc\bdcadel\public" -lang:fr`

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	`adeliadoc -action:init -project:"d:\adeliaDoc\bdcadel\public" -title:"API Documentation V1" -lang:en`

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	`adeliadoc -action:generate -env:bdcadel@hostname -project:"d:\adeliaDoc\bdcadel\public" -format:html -force`

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 "`log`" du projet (fichier adeliadoc.log). Attention : pour les actions init et delete , il est nécessaire de renseigner explicitement le nom absolu du fichier rapport.
Actions	init : facultatif generate : facultatif make : facultatif cleanup : facultatif delete : facultatif
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	cas d'un nom explicite pour le fichier log : `adeliadoc -action: generate -env:bdcadel -project:"d:\adeliaDoc\bdcadel\public" -format:html -log:"c:\temp\adeliadoc_bdcadel_public.log"` cas d'emploi avec valeur par défaut : `adeliadoc -action:generate -env:bdcadel -project:"d:\adeliaDoc\bdcadel\public" -format:html -log`

↑ Haut de page

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 .

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.

↑ Haut de page

Les paramètres d'appel AdeliaDoc

Généralités

Tableau descriptif des paramètres

Description détaillée des paramètres

Paramètre action

Paramètre project

Paramètre env

Paramètre app_area

Paramètre build_comp

Paramètre pgm

Paramètre filter

Paramètre format

Paramètre lang

Paramètre title

Paramètre force

Paramètre log

Codes retour d'AdeliaDoc