This is an automated email from the git hooks/post-receive script. New commit to branch develop in repository nuiton-config. See https://gitlab.nuiton.org/nuiton/nuiton-config.git commit ab3e1ca783da059be2d87cad6edd55d5d2749bcb Author: Tony CHEMIT <chemit@codelutin.com> Date: Sun Oct 2 15:50:28 2016 +0200 improve doc --- nuiton-config-example/pom.xml | 37 ++++ nuiton-config-example/src/site/apt/index.apt.vm | 92 +++------- nuiton-config-maven-plugin/src/site/apt/index.apt | 4 +- src/site/apt/index.apt | 6 +- src/site/apt/usage.apt.vm | 207 ++++++++++++---------- 5 files changed, 184 insertions(+), 162 deletions(-) diff --git a/nuiton-config-example/pom.xml b/nuiton-config-example/pom.xml index 02f2d1b..1e2b4ad 100644 --- a/nuiton-config-example/pom.xml +++ b/nuiton-config-example/pom.xml @@ -93,6 +93,43 @@ <profiles> <profile> + <id>reporting</id> + <activation> + <property> + <name>performRelease</name> + <value>true</value> + </property> + </activation> + <build> + <plugins> + <plugin> + <artifactId>maven-antrun-plugin</artifactId> + <executions> + <execution> + <id>Copy files to site</id> + <phase>pre-site</phase> + <configuration> + <target> + <copy todir="${project.reporting.outputDirectory}/model" failonerror="true" overwrite="true"> + <fileset dir="src/main/config"> + <include name="*.toml"/> + <include name="*.yaml"/> + </fileset> + </copy> + </target> + </configuration> + <goals> + <goal>run</goal> + </goals> + </execution> + </executions> + </plugin> + </plugins> + </build> + + </profile> + + <profile> <id>assembly-profile</id> <activation> <property> diff --git a/nuiton-config-example/src/site/apt/index.apt.vm b/nuiton-config-example/src/site/apt/index.apt.vm index d2b3820..031f5aa 100644 --- a/nuiton-config-example/src/site/apt/index.apt.vm +++ b/nuiton-config-example/src/site/apt/index.apt.vm @@ -30,19 +30,19 @@ Utilisation Ce module est un exemple d'utilisation de <<nuiton-config>>. - Le principe est simple + Le principe est simple : - * Décrire la configuration dans un fichier au format simple ; + [[1]] Décrire la configuration dans un fichier texte ; - * Générer via le plugin maven le code java à partir de la description ; + [[2]] Générer via le plugin maven le code java à partir de la description ; - * Utiliser la classe java de configuration qui a été générée ; + [[3]] Utiliser la classe java de configuration qui a été générée ; - * Documenter votre configuration via le plugin de report. + [[4]] Documenter votre configuration via le plugin de report. [] - Vous pouvez télécharger les sources du projet {{{https://nexus.nuiton.org/nexus/service/local/artifact/maven/redirect?g=public&g=org.nuiton&a=nuiton-config-example&v=${project.version}&e=zip&c=full}ici}}. + Vous pouvez télécharger les sources du projet {{{https://nexus.nuiton.org/nexus/service/local/artifact/maven/redirect?r=public&g=org.nuiton&a=nuiton-config-example&v=${project.version}&e=zip&c=full}ici}}. Dans cet exemple, nous utilisations toutes les valeurs par défaut fournies par le plugin (ZéroConf). @@ -54,21 +54,21 @@ Utilisation <version>${project.version}</version> +------------------------------------------------ - En utilisant les conventions du projet, la classe de configuration se nommera <<org.nuiton.config.example.NuitonConfigExampleConfig>>. + En utilisant les conventions du plugin, la classe de configuration se nommera <<org.nuiton.config.example.NuitonConfigExampleConfig>>. * Décrire les options et les actions de la configuration Dans notre exemple, nous avons quatre options dans la configuration : - * <<lastName>> le nom de l'utilisateur + [[1]] <<lastName>> le nom de l'utilisateur - * <<firstName>> le prénom de passe de l'utilisateur + [[2]] <<firstName>> le prénom de passe de l'utilisateur - * <<email>> le courriel de l'utilisateur + [[3]] <<email>> le courriel de l'utilisateur - * <<twitter>> le compte twitter de l'utilisateur + [[4]] <<twitter>> le compte twitter de l'utilisateur - * <<age>> l'age de l'utilisateur + [[5]] <<age>> l'age de l'utilisateur [] @@ -78,50 +78,8 @@ Utilisation [] - Voici le fichier de description de cette configuration : - -+------------------------------------------------ -description: Exemple de configuration -options: - - !option - name: firstName - key: identity.firstName - type: string - description: Prénom de l'utilisateur - defaultValue: Joshua - - !option - name: lastName - key: identity.lastName - type: string - description: Nom de l'utilisateur - defaultValue: Bloch - - !option - name: email - key: identity.email - type: string - description: Courriel de l'utilisateur - - !option - name: twitter - key: identity.twitter - type: string - description: Compte Twitter de l'utilisateur - defaultValue: jbloch - - !option - name: age - key: identity.age - type: int - description: age de l'utilisateur - defaultValue: 56 -actions: - - !action - name: help - description: Pour afficher l'aide - action: org.nuiton.config.example.NuitonConfigExample#help - aliases: - - "-h" - - "--help" -+------------------------------------------------ - + Voir le fichier de configuration au format {{{./model/NuitonConfigExample.toml}Toml}} ou + {{{./model/NuitonConfigExample.yaml}Yaml}}. * Générer les classes de configuration @@ -130,7 +88,7 @@ actions: +------------------------------------------------ <plugin> <groupId>${project.groupId}</groupId> - <artifactId>${project.artifactId}</artifactId> + <artifactId>nuiton-config-maven-plugin</artifactId> <version>${project.version}</version> <executions> <execution> @@ -157,26 +115,26 @@ target └── example ├── GeneratedNuitonConfigExampleConfig.java (2) ├── GeneratedNuitonConfigExampleConfigProvider.java (3) - ├── NuitonConfigExampleConfig.java (4) +---------------------> ├── NuitonConfigExampleConfig.java (4) <---------------------------- ├── NuitonConfigExampleConfigAction.java (5) ├── NuitonConfigExampleConfigOption.java (6) └── NuitonConfigExampleConfigProvider.java (7) +------------------------------------------------ - * (1) fichier qui enregistre (en utilisant le mécanisme ServiceLoader), le provider de configuration généré + [[1]] fichier qui enregistre (en utilisant le mécanisme ServiceLoader), le provider de configuration généré - * (2) classe abstraite de configuration + [[2]] classe abstraite de configuration - * (3) classe abstraite de provider + [[3]] classe abstraite de provider - * <<(4) classe de configuration prête à l'emploi dans votre application>> + [[4]] * <<(classe de configuration prête à l'emploi dans votre application>> - * (5) classe qui décrit les actions + [[5]] classe qui décrit les actions - * (6) classe qui décrit les options + [[6]] classe qui décrit les options - * (5) provider de configuration prêt à l'emploi (il sert pour la génération de la documentation notamment) + [[7]] provider de configuration prêt à l'emploi (il sert pour la génération de la documentation notamment) [] @@ -192,7 +150,7 @@ target +------------------------------------------------ <plugin> <groupId>${project.groupId}</groupId> - <artifactId>${project.artifactId}</artifactId> + <artifactId>nuiton-config-maven-plugin</artifactId> <version>${project.version}</version> <reportSets> <reportSet> @@ -204,4 +162,4 @@ target </plugin> +------------------------------------------------ - Retrouver le rapport généré ({{{./config-report.html}ici}}). + ({{{./config-report.html}Voir rapport généré}}). diff --git a/nuiton-config-maven-plugin/src/site/apt/index.apt b/nuiton-config-maven-plugin/src/site/apt/index.apt index a1ecbab..4a35613 100644 --- a/nuiton-config-maven-plugin/src/site/apt/index.apt +++ b/nuiton-config-maven-plugin/src/site/apt/index.apt @@ -30,9 +30,9 @@ Présentation - Le plugin propose quatre goal : + Le plugin propose quatre goals : - * Goal {{{./generate-mojo.html/}generate}} : permet de générer les classes java de la configuration à partir d'un modèle de description ; + * Goal {{{./generate-mojo.html}generate}} : permet de générer les classes java de la configuration à partir d'un modèle de description ; * Goal {{{./describe-mojo.html}describe}} : permet de générer le modèle de description à partir des classes java de la configuration ; diff --git a/src/site/apt/index.apt b/src/site/apt/index.apt index 8ca40ac..9d1d33c 100644 --- a/src/site/apt/index.apt +++ b/src/site/apt/index.apt @@ -32,7 +32,7 @@ Présentation * une api simple de gestion de configuration (voir {{{./nuiton-config/index.html}module API}}) ; - * un plugin maven pour générer la configuration et une documentation (voir {{{./nuiton-config-maven-plugin/index.html}module Maven}}) ; + * un plugin maven pour générer la configuration à partir de sa description textuelle et sa documentation (voir {{{./nuiton-config-maven-plugin/index.html}module Maven}}) ; * un projet exemple qui utilise <<nuiton-config>> (voir {{{./nuiton-config-example/index.html} module Exemple}}). @@ -43,9 +43,9 @@ Philosophie du projet Le but de ce projet est de fournir une manière simple et efficace de gérer une ou plusieurs configurations dans un projet Java. - Pour ce faire, on propose de décrire les options et actions d'une configuration dans un format simple et concis (yaml) + Pour ce faire, on propose de décrire la configuration dans un format textuel simple et concis (toml ou yaml). - Ensuite on utilise le plugin de génération fourni pour générer une classe de configuration prête à l'emploi. + Ensuite on utilise le plugin de génération fourni pour générer une classe Java de configuration prête à l'emploi. On peut aussi par la suite générer un rapport <maven> de documentation de la configuration. diff --git a/src/site/apt/usage.apt.vm b/src/site/apt/usage.apt.vm index 09e359c..97915fb 100644 --- a/src/site/apt/usage.apt.vm +++ b/src/site/apt/usage.apt.vm @@ -26,12 +26,32 @@ 2016-09-30 ---- -Décrire les options et les actions d'une configuration +Première étape : décrire sa configuration - Un format simple a été conçu pour décrire les options et actions d'une configuration. Il est base sur le format <<yaml>>. + La première chose à faire est de décrire sa configuration (options, actions, description, ...). + + Il existe deux formats ({{{https://github.com/toml-lang/toml}Toml}}) ou ({{{http://yaml.org/}Yaml}}) pour décrire la configuration. + + Le format par défaut est le <<Toml>>. + +* Comment décrire une configuration ? Une configuration est composée d'une description, d'options et d'actions (optionnelles) +** Format Toml + ++------------------------------------------------ +description = "Exemple de configuration" +[[options]] +[[options]] +... +[[actions]] +[[actions]] +... ++------------------------------------------------ + +** Format Yaml + +------------------------------------------------ description: Exemple de configuration options: @@ -44,19 +64,19 @@ actions: ... +------------------------------------------------ -* Comment décrire une option +* Comment décrire une option ? Une option contient les propriétés suivantes : - * <<name>> : [obligatoire] nom de l'option (dans la configuration générée, on pourra accéder à cette option via des getters/setters adaptés) ; + [[1]] <<name>> : [obligatoire] nom de l'option (dans la configuration générée, on pourra accéder à cette option via des getters/setters adaptés) ; - * <<key>> : [obligatoire] la clef de l'option à utiliser pour la sauvegarde dans le fichier de configuration ; + [[2]] <<key>> : [obligatoire] la clef de l'option à utiliser pour la sauvegarde dans le fichier de configuration ; - * <<type>> : [obligatoire] type de l'option (voir plus bas) ; + [[3]] <<type>> : [obligatoire] type de l'option (voir plus bas) ; - * <<description>> : [obligatoire] la description de l'option ou une clef i18n de traduction (si useNuitonI18n est activé) ; + [[4]] <<description>> : [obligatoire] la description de l'option ou une clef i18n de traduction (si useNuitonI18n est activé) ; - * <<defaultvalue>> : [optionnel] une valeur par défaut. + [[5]] <<defaultvalue>> : [optionnel] une valeur par défaut. [] @@ -68,29 +88,40 @@ actions: * les types primitifs (boolean, int, ...) et leur équivalents en objet (Boolean, Integer, ...) - * <<file>> : <<java.io.File>> + * <<file>> : <java.io.File> - * <<class>> : <<java.lang.Class>> + * <<class>> : <java.lang.Class> - * <<url>> : <<java.net.URL>> + * <<url>> : <java.net.URL> - * <<color>> : <<java.awt.Color>> + * <<color>> : <java.awt.Color> - * <<keystroke>> : <<javax.swing.KeyStroke>> + * <<keystroke>> : <javax.swing.KeyStroke> - * <<version>> : <<org.nuiton.version.Version>> + * <<version>> : <org.nuiton.version.Version> - * <<date>> : <<java.util.Date>> + * <<date>> : <java.util.Date> - * <<time>> : <<java.sql.Time>> + * <<time>> : <java.sql.Time> - * <<timestamp>> : <<java.sql.Timestamp>> + * <<timestamp>> : <java.sql.Timestamp> [] Pour pouvez aussi mettre n'importe quelle classe java qui dispose d'une constructeur publique via son nom qualifié. -** Exemple d'une option +** Exemple d'une option au format Toml + ++------------------------------------------------ +[[options]] +name = "age" +key = "identity.age" +description = "age de l'utilisateur" +type = "int" +defaultValue = "56" ++------------------------------------------------ + +** Exemple d'une option au format Yaml +------------------------------------------------ - !option @@ -101,21 +132,31 @@ actions: defaultValue: 56 +------------------------------------------------ -* Comment décrire une action +* Comment décrire une action ? Une action contient les propriétés suivantes : - * <<name>> : [obligatoire] nom de l'action ; + [[1]] <<name>> : [obligatoire] nom de l'action ; - * <<description>> : [obligatoire] la description de l'option ou une clef i18n de traduction (si useNuitonI18n est activé) ; + [[2]] <<description>> : [obligatoire] la description de l'option ou une clef i18n de traduction (si useNuitonI18n est activé) ; - * <<action>> : [obligatoire] l'action à executer ; + [[3]] <<action>> : [obligatoire] l'action à executer ; - * <<aliases>> : [optionnel] des alias pour activer l'action. + [[4]] <<aliases>> : [optionnel] des alias pour activer l'action. [] -** Exemple d'une action +** Exemple d'une action au format Toml + ++------------------------------------------------ +[[actions]] +name = "help" +description = "Pour afficher l'aide" +action = "org.nuiton.config.example.NuitonConfigExample#help" +aliases = ["-h", "--help"] ++------------------------------------------------ + +** Exemple d'une action au format Yaml +------------------------------------------------ - !action @@ -129,18 +170,17 @@ actions: * Exemple - Dans notre exemple, nous avons cinq options dans la configuration : - * <<lastName>> le nom de l'utilisateur + [[1]] <<lastName>> le nom de l'utilisateur - * <<firstName>> le prénom de passe de l'utilisateur + [[2]] <<firstName>> le prénom de passe de l'utilisateur - * <<email>> le courriel de l'utilisateur + [[3]] <<email>> le courriel de l'utilisateur - * <<twitter>> le compte twitter de l'utilisateur + [[4]] <<twitter>> le compte twitter de l'utilisateur - * <<age>> l'age de l'utilisateur + [[5]] <<age>> l'age de l'utilisateur [] @@ -150,53 +190,13 @@ actions: [] - Voici la description qui correspond : + Voir le fichier de configuration au format {{{./nuiton-config-example/model/NuitonConfigExample.toml}Toml}} ou + {{{./nuiton-config-example/model/NuitonConfigExample.yaml}Yaml}}. -+------------------------------------------------ -description: Exemple de configuration -options: - - !option - name: firstName - key: identity.firstName - type: string - description: Prénom de l'utilisateur - defaultValue: Joshua - - !option - name: lastName - key: identity.lastName - type: string - description: Nom de l'utilisateur - defaultValue: Bloch - - !option - name: email - key: identity.email - type: string - description: Courriel de l'utilisateur - - !option - name: twitter - key: identity.twitter - type: string - description: Compte Twitter de l'utilisateur - defaultValue: jbloch - - !option - name: age - key: identity.age - type: int - description: age de l'utilisateur - defaultValue: 56 -actions: - - !action - name: help - description: Pour afficher l'aide - action: org.nuiton.config.example.NuitonConfigExample#help - aliases: - - "-h" - - "--help" -+------------------------------------------------ +Deuxième étape : Générer la configuration -Générer la configuration - - Il suffit d'excuter le goal <<generate>> en lui indiquant le chemin de description de la configuration. + Il suffit d'excuter le goal {{{./nuiton-config-maven-plugin/generate-mojo.html}generate}} en lui indiquant + le chemin de description de la configuration. +------------------------------------------------ <plugin> @@ -213,19 +213,19 @@ Générer la configuration </plugin> +------------------------------------------------ + Le format par défaut utilisé est le <<Toml>>, vous pouvez aussi utiliser le format <<yaml>>. + Par défaut, on place le fichier de description dans le répertoire <<src/main/config>>. Si on ne précise pas de nom de modèle, le plugin utilise l'identifiant de l'artefact en le transformant au format «Camel Case». - Par exemple, si l'<artifactId> est <<nuiton-config-example>>, le nom de fichier est <<NuitonConfigExample.yml>> + Par exemple, si l'<artifactId> est <<nuiton-config-example>>, le nom de fichier est <<NuitonConfigExample.toml>> Si vous voulez utiliser un autre nom, ajouter la propriété de configuration <<modelName>>. - Pour plus de détails ce le plugin, consulter la page de {{{./generate-mojo.html/}détail}}. - * Utilisation de Nuiton-I18n - Il est possible d'utiliser {{{http://nuiton-i18n.nuiton.org/v/latest}Nuiton-I18n}} pour externaliser les descriptions + Il est possible d'utiliser {{{http://i18n.nuiton.org/v/latest}Nuiton-I18n}} pour externaliser les descriptions de la configuration, options et actions. Il suffit d'activer la propriété <<useNuitonI18n>> dans le plugin de génération. @@ -264,28 +264,29 @@ target +------------------------------------------------ - * (1) fichier qui enregistre (en utilisant le mécanisme ServiceLoader), le provider de configuration généré + [[1]] fichier qui enregistre (en utilisant le mécanisme ServiceLoader), le provider de configuration généré - * (2) classe abstraite de configuration + [[2]] classe abstraite de configuration - * (3) classe abstraite de provider + [[3]] classe abstraite de provider - * <<(4) La classe de configuration prête à l'emploi dans votre application>> + [[4]] <<classe de configuration prête à l'emploi dans votre application>> - * (5) classe qui décrit les actions + [[5]] classe qui décrit les actions - * (6) classe qui décrit les options + [[6]] classe qui décrit les options - * (5) provider de configuration prêt à l'emploi (il sert pour la génération de la documentation notamment) + [[7]] provider de configuration prêt à l'emploi (il sert pour la génération de la documentation notamment) [] <« Et Voila ! »>, vous pouvez utiliser votre configuration en Java. -Pour générer la documentation de votre configuration +Troisième étape : générer la documentation de votre configuration - Utiliser le mojo de report <<report>> ou <<aggregate-report>> pour générer la documentation sur les configurations - détectées via les providers. + Utiliser le mojo de report {{{./nuiton-config-maven-plugin/report-mojo.html}report}} ou + {{{./nuiton-config-maven-plugin/aggregate-report-mojo.html}aggregate-report}} pour générer la documentation + sur les configurations détectées via les providers. +------------------------------------------------ <plugin> @@ -302,4 +303,30 @@ Pour générer la documentation de votre configuration </plugin> +------------------------------------------------ - {{{./nuiton-config-example/config-report.html}Retrouver un exemple de rapport généré }}. + {{{./nuiton-config-example/config-report.html}Exemple de rapport généré}}. + +Décrire une configuration à partir des classes java (migration) + + Il est possible facilement de convertir des classes java de configuration en fichier de description (ensuite il suffit + alors de supprimer les classes java et de les générer iva le plugin). + + Pour cela il faut utiliser le goal {{{./nuiton-config-maven-plugin/describe-mojo.html}describe}}. + + Il faut au préalable que vous ayez défini un <provider> de configuration (Voir ApplicationConfigProvider TODO). + + Lancer ensuite en ligne de commande + ++------------------------------------------------ +mvn nuiton-config:describe -Dconfig.providerName=NuitonConfigExample ++------------------------------------------------ + + Cela va générer le fichier (toml) à l'emplacement suivant : + ++------------------------------------------------ +src +└── main + └── config + └── NuitonConfigExample.toml ++------------------------------------------------ + + Vous pouvez aussi choisir le format <Yaml> en passant l'option <<-Dconfig.format=yaml>>. -- To stop receiving notification emails like this one, please contact nuiton.org SCM administrator <admin+scm@nuiton.org>.