documentation

This commit is contained in:
Emmanuel Garette 2021-01-30 19:42:46 +01:00
parent e1fd29001b
commit 683bd862f5
10 changed files with 325 additions and 47 deletions

View File

@ -1,23 +0,0 @@
Valeur automatiquement modifiée
===============================
Une variable avec valeur automatiquement modifiée est une variable dont la valeur sera considéré comme modifié quand le serveur sera déployé.
Voici un variable a valeur automatiquement modifiée :
<variable name="my_variable" type="oui/non" description="My variable" auto_save="True">
Dans ce cas la valeur est fixée à la valeur actuelle.
Par exemple, si la valeur de cette variable est issue d'un calcul, la valeur ne sera plus recalculée.
Valeur en lecture seule automatique
===================================
Une variable avec valeur en lecture seule automatique est une variable dont la valeur ne sera plus modifiable par l'utilisateur quand le serveur sera déployé.
Voici un variable à valeur en lecture seule automatique :
<variable name="my_variable" type="oui/non" description="My variable" auto_freeze="True">
Dans ce cas la valeur est fixée à la valeur actuelle et elle ne sera plus modifiable par l'utilisateur.
Par exemple, si la valeur de cette variable est issue d'un calcul, la valeur ne sera plus recalculée.

2
doc/check.rst Normal file
View File

@ -0,0 +1,2 @@
<!ATTLIST variable remove_check (True|False) "False">

1
doc/condition.rst Normal file
View File

@ -0,0 +1 @@
<!ATTLIST variable remove_condition (True|False) "False">

79
doc/family.rst Normal file
View File

@ -0,0 +1,79 @@
Famille
=======
Une famille
-----------
Une famille est un conteneur de variables.
Pour décrire une famille il faut mettre au minimum un nom :
<family name="my_family"/>
Cette famille doit être placé dans une balise "variables" :
<variables>
<family name="my_family"/>
</variables>
Description et aide sur la famille
----------------------------------
En plus d'un nom, il est possible de mettre une "description" à la famille. C'est une information "utilisateur" qui nous permettra d'avoir des informations complémentaires sur le contenu de cette famille :
<family name="my_family" description="This is a great family"/>
En plus de la description, il est possible de préciser une aide complémentaire :
<family name="my_family" help="This is a great family"/>
Mode de la famille
------------------
Le mode par défaut d'une famille correspond au mode le plus petite des variables dans cette famille.
Changer le mode d'une famille permet de définir le mode par défaut des variables inclusent dans cette famille.
Pour définir le mode :
<family name="my_family" mode="expert"/>
Cacher une famille
------------------
Il est possible de cacher une famille, ainsi toutes les variables inclusent dans cette famille.
Cacher une famille signifie qu'elle ne sera pas visible lorsqu'on modifie la configuration du service.
Par contre ces variables sont accessibles lorsqu'on va utiliser ces variables.
Pour cacher une famille :
<family name="my_family" hidden="True"/>
Les familles crées dynamiquement
--------------------------------
Pour créer une famille crées dynamiquement, il faut créer une family fictive lié à une variable.
Le nom et la description de la famille et des variables qu'elle contient sera en réalité le prefix du nouveau nom/description. Le suffix viendra de la variable liée.
Par exemple :
<family name='my_family'>
<variable name='varname' multi="True">
<value>val1</value>
<value>val2</value>
</variable>
</family>
<family name='my_dyn_family\_' dynamic="varname description="Describe "">
<variable name='my_dyn_var\_'/>
</family>
Créera trois familles :
- la famille : "my_family"
- la famille dynamique : "my_dyn_family_val1" avec la description "Describe val1"
- la famille dynamique : "my_dyn_family_val2" avec la description "Describe val2"
Dans la famille dynamique "my_dyn_family_val1" on retrouvera une variable "my_dyn_var_val1".
Bien évidement si le contenu de "varname" venait a évolué, de nouvelles familles dynamiques pouvent apparaitre ou des familles dynamiques peuvent disparaître.

View File

@ -6,11 +6,11 @@ Une variable calculée est une variable donc sa valeur est le résultat d'une fo
Variable avec une valeur par défaut calculée Variable avec une valeur par défaut calculée
-------------------------------------------- --------------------------------------------
Créons une variable de type "oui/non" donc la valeur est retournée par la fonction "return_no" : Créons une variable dont la valeur est retournée par la fonction "return_no" :
<variables> <variables>
<family name="family"> <family name="family">
<variable name="my_calculated_variable" type="oui/non" description="My calculated variable"/> <variable name="my_calculated_variable"/>
</family> </family>
</variables> </variables>
<constraints> <constraints>
@ -20,14 +20,14 @@ Créons une variable de type "oui/non" donc la valeur est retournée par la fonc
Puis créons la fonction "return_no" : Puis créons la fonction "return_no" :
def return_no(): def return_no():
return 'non' return 'no'
Dans ce cas, la valeur par défaut est la valeur retournée par la fonction (ici "non"), elle sera calculée tant que l'utilisateur n'a pas de spécifié une valeur à cette variable. Dans ce cas, la valeur par défaut est la valeur retournée par la fonction (ici "no"), elle sera calculée tant que l'utilisateur n'a pas de spécifié une valeur à cette variable.
Si l'utilisateur à définit une valeur par défaut à "my_calculated_variable" : Si l'utilisateur à définit une valeur par défaut à "my_calculated_variable" :
<variable name="my_calculated_variable" type="oui/non" description="My calculated variable"> <variable name="my_calculated_variable">
<value>oui</value> <value>yes</value>
</variable> </variable>
Cette valeur par défaut sera complètement ignorée. Cette valeur par défaut sera complètement ignorée.
@ -37,7 +37,7 @@ Variable avec une valeur calculée
En ajoutant le paramètre "hidden" à "True" dans la variable précédente, l'utilisateur n'aura plus la possibilité de modifié la valeur. La valeur de la variable sera donc systématiquement calculée : En ajoutant le paramètre "hidden" à "True" dans la variable précédente, l'utilisateur n'aura plus la possibilité de modifié la valeur. La valeur de la variable sera donc systématiquement calculée :
<variable name="my_calculated_variable" type="oui/non" description="My calculated variable" hidden="True"/> <variable name="my_calculated_variable" hidden="True"/>
Si une condition "hidden_if_in" est spécifié à la variable, la valeur sera modifiable par l'utilisateur si elle n'est pas cachée mais elle sera systèmatiquement calculée (même si elle a déjà était modifiée) si la variable est cachée. Si une condition "hidden_if_in" est spécifié à la variable, la valeur sera modifiable par l'utilisateur si elle n'est pas cachée mais elle sera systèmatiquement calculée (même si elle a déjà était modifiée) si la variable est cachée.
@ -54,7 +54,7 @@ Déclarons un calcul avec paramètre :
<constraints> <constraints>
<fill name="return_value" target="my_calculated_variable"> <fill name="return_value" target="my_calculated_variable">
<param>non</param> <param>no</param>
</fill> </fill>
</constraints> </constraints>
@ -63,7 +63,7 @@ Créons la fonction correspondante :
def return_value(value): def return_value(value):
return value return value
La variable aura donc "non" comme valeur puisque le paramètre aura la valeur fixe "non". La variable aura donc "no" comme valeur puisque le paramètre aura la valeur fixe "no".
Paramètre nommée Paramètre nommée
---------------- ----------------
@ -72,11 +72,11 @@ Déclarons une contrainte avec un paramètre nommée :
<constraints> <constraints>
<fill name="return_value" target="my_calculated_variable"> <fill name="return_value" target="my_calculated_variable">
<param name="valeur">non</param> <param name="valeur">no</param>
</fill> </fill>
</constraints> </constraints>
Dans ce cas la fonction return_value sera exécuté avec le paramètre nommé "valeur" dont sa valeur sera "non". Dans ce cas la fonction return_value sera exécuté avec le paramètre nommé "valeur" dont sa valeur sera "no".
Paramètre avec un nombre Paramètre avec un nombre
------------------------ ------------------------
@ -93,10 +93,10 @@ Créons la fonction correspondante :
def return_value_with_number(value): def return_value_with_number(value):
if value == 1: if value == 1:
return 'non' return 'no'
return 'oui' return 'yes'
La variable aura donc "non" comme valeur puisque le paramètre aura la valeur fixe "1". La variable aura donc "no" comme valeur puisque le paramètre aura la valeur fixe "1".
Paramètre dont la valeur est issue d'une autre variable Paramètre dont la valeur est issue d'une autre variable
------------------------------------------------------- -------------------------------------------------------
@ -105,7 +105,7 @@ Créons deux variables avec une contrainte de type variable qui contient le nom
<variables> <variables>
<family name="family"> <family name="family">
<variable name="my_calculated_variable" type="oui/non" description="My calculated variable"/> <variable name="my_calculated_variable"/>
<variable name="my_variable" type="number" description="My variable"> <variable name="my_variable" type="number" description="My variable">
<value>1</value> <value>1</value>
</variable> </variable>
@ -117,8 +117,8 @@ Créons deux variables avec une contrainte de type variable qui contient le nom
</fill> </fill>
</constraints> </constraints>
Si l'utilisateur laisse la valeur 1 à "my_variable", la valeur par défault de la variable "my_calculated_variable" sera "non". Si l'utilisateur laisse la valeur 1 à "my_variable", la valeur par défault de la variable "my_calculated_variable" sera "no".
Si la valeur de "my_variable" est différent de 1, la valeur par défaut de la variable "my_calculated_variable" sera "oui". Si la valeur de "my_variable" est différent de 1, la valeur par défaut de la variable "my_calculated_variable" sera "yes".
Paramètre dont la valeur est issue d'une information de la configuration Paramètre dont la valeur est issue d'une information de la configuration
------------------------------------------------------------------------ ------------------------------------------------------------------------
@ -148,7 +148,7 @@ Un paramètre de type "variable" peut être "optional" :
<variables> <variables>
<family name="family"> <family name="family">
<variable name="my_calculated_variable" type="oui/non" description="My calculated variable"/> <variable name="my_calculated_variable"/>
</family> </family>
</variables> </variables>
<constraints> <constraints>
@ -263,7 +263,7 @@ Dans un premier dictionnaire déclarons notre variable et notre calcule :
<variables> <variables>
<family name="family"> <family name="family">
<variable name="my_calculated_variable" type="oui/non" description="My calculated variable"/> <variable name="my_calculated_variable"/>
</family> </family>
</variables> </variables>
<constraints> <constraints>
@ -283,3 +283,28 @@ Dans un second dictionnaire il est possible de redéfinir le calcul :
Dans ce cas, à aucun moment la fonction "return_no" ne sera exécuté. Seul la fonction "return_yes" le sera. Dans ce cas, à aucun moment la fonction "return_no" ne sera exécuté. Seul la fonction "return_yes" le sera.
Redéfinition avec suppression d'un calcul
-----------------------------------------
Il se peut que dans un dictionnaire on décide de définir une valeur par défaut à une variable via un calcul.
Dans un second dictionnaire il est possible de supprimer ce calcul.
Dans un premier dictionnaire déclarons notre variable et notre calcule :
<variables>
<family name="family">
<variable name="my_calculated_variable"/>
</family>
</variables>
<constraints>
<fill name="return_no" target="my_calculated_variable"/>
</constraints>
Dans un second dictionnaire supprimer ce calcul :
<variables>
<family name="family">
<variable name="my_calculated_variable" redefine="True" remove_fill="True"/>
</family>
</variables>

0
doc/index.rst Normal file
View File

8
doc/mode.rst Normal file
View File

@ -0,0 +1,8 @@
Mode
====
Il existe trois "mode" dans Rougail :
- basic : variables indispensables à la mise en place d'un service
- normal : variables couramment modifié par l'utilisateur
- expert : variables a manipuler avec précausion et en toute connaissance de cause

View File

@ -1,13 +1,189 @@
Variable Variable
======== ========
Un variable
-----------
Une variable est forcement dans une famille. Il faut donc déjà avoir créer une famille.
Une variable est déjà un nom. C'est à dire qu'on pourra utiliser plus tard la variable via ce nom.
<variable name="my_variable"/>
Description et aide sur la variable
----------------------------------
En plus d'un nom, il est possible de mettre une "description" à la variable. C'est une information "utilisateur" qui nous permettra d'avoir des informations complémentaires sur le contenu de cette variable :
<variable name="my_variable" description="This is a greate variable"/>
En plus de la description, il est possible de préciser une aide complémentaire :
<variable name="my_variable" help="This is a greate variable"/>
Le type de la variable
----------------------
Une variable a un type. Ce type permet de définir les valeurs acceptées par cette variable :
- string : chaine de caractère (type par défaut)
- number : un nombre
- float : un chiffre flottant
- boolean : True ou False si aucune valeur n'est défini la valeur par défaut cette variable sera True
- password : un mot de passe
- mail : une adresse mail
- filename : nom de fichier au sens Unix (exemple : '/etc/passwd')
- date : une date au format "%Y-%m-%d" (exemple : "2021-01-30")
- unix_user : nom d'utilisateur au sens Unix
- ip : n'importe quelle adresse IPv4
- cidr : n'importe quelle adresse IPv4 au format CIDR
- local_ip : adresse IPv4 sur un réseau local, si l'adresse IPv4 n'est pas local, un warning sera afficher mais la valeur sera accepté tout de même
- netmask : masque d'une adresse IPv4
- network : adresse réseau
- network_cidr : adresse réseau au format CIDR
- broadcast : adresse de diffusion
- netbios : nom netbios
- domain : nom de domaine
- hostname : nom d'hôte
- web_address : adresse web (http://www.cadoles.com/)
- port : port
- mac : adresse MAC
- schedule : périodicité du schedule, les valeurs possibles sont "none", "daily", "weekly" ou "monthly"
- schedulemod : type de schedule, les valeurs possibles sont "pre" ou "post"
Pour définir le type d'une variable :
<variable name="my_variable" type="number"/>
Variable à valeur multiple
--------------------------
Par défaut une variable ne peut acceuillir qu'une seule valeur. Il peut être utile de pouvoir spécifier plusieurs valeurs à une même variable.
Pour définir une variable à valeur multiple :
<variable name="my_variable" multi="True"/>
Mode de la variable
-------------------
Le mode par défaut d'une variable correspond au mode de la famille.
Pour définir le mode :
<variable name="my_variable" mode="expert"/>
Cacher une variable
-------------------
Il est possible de cacher une variable.
Cacher une variable signifie qu'elle ne sera pas visible lorsqu'on modifie la configuration du service.
Par contre cette variable sont accessibles lorsqu'on va l'utiliser.
Pour cacher une variable :
<variable name="my_variable" hidden="True"/>
Désactiver une variable
-----------------------
Il est possible de désactiver une variable.
Désactiver une variable signifie qu'elle ne sera pas visible lorsqu'on modifie la configuration du service mais également lorsqu'on va l'utiliser.
Pour désactiver une variable :
<variable name="my_variable" disabled="True"/>
Variable obligatoire Variable obligatoire
-------------------- --------------------
Variable dont une valeur est requise : Variable dont une valeur est requise :
<variables> <variable name="my_variable" mandatory="True"/>
<family name="family">
<variable name="my_variable" type="oui/non" description="My variable" mandatory="True"/> Valeur par défaut d'une variable
</family> --------------------------------
</variables>
Il est possible de fixer les valeurs par défaut d'une variable :
<variable name="my_variable">
<value>value</value>
</variable>
Pour une variable multiple, il est possible de préciser plusieurs valeurs :
<variable name="my_variable" multi="True">
<value>value 1</value>
<value>value 2</value>
</variable>
Une valeur par défaut peut également être `une valeur calculer <fill.rst>`.
Redéfinir une variable
----------------------
Il est possible de définir une variable dans un dictionnaire et de changer son comportement dans une second dictionnaire.
Attention trois attributs ne sont redéfinisable :
- name
- type
- multi
Créons notre variable :
<variable name="my_variable"/>
Et redéfinisons là :
<variable name="my_variable" redefine="True" description="New description"/>
Créer une variable inexistante
------------------------------
Il est parfois utile de créer une variable si elle n'existe pas dans un autre dictionnaire :
<variable name="my_variable" exists="False"/>
Si cette variable existe dans un autre dictionnaire, elle ne sera pas modifier ni recréé
Redéfinir une variable si elle existe
-------------------------------------
Parfois on veut pouvoir redéfinir une variable mais seulement dans le cas où elle existe déjà :
<variable name="my_variable" redefine="True" exists="True" hidden="True"/>
Variable à valeur automatiquement modifiée
------------------------------------------
Une variable avec valeur automatiquement modifiée est une variable dont la valeur sera considéré comme modifié quand le serveur sera déployé.
Voici une variable a valeur automatiquement modifiée :
<variable name="my_variable" auto_save="True">
<value>my_value</value>
</variable>
Dans ce cas la valeur est fixée à la valeur actuelle.
Par exemple, si la valeur de cette variable est issue d'un calcul, la valeur ne sera plus recalculée.
Ces variables sont généralement des variables obligatoires. En effet ces variable ne sont automatiquement modifiées que si elles sont une valeurs.
Variable à valeur en lecture seule automatique
----------------------------------------------
Une variable avec valeur en lecture seule automatique est une variable dont la valeur ne sera plus modifiable par l'utilisateur quand le serveur sera déployé.
Voici un variable à valeur en lecture seule automatique :
<variable name="my_variable" auto_freeze="True"/>
Dans ce cas la valeur est fixée à la valeur actuelle et elle ne sera plus modifiable par l'utilisateur.
Par exemple, si la valeur de cette variable est issue d'un calcul, la valeur ne sera plus recalculée.
Ces variables sont généralement des variables obligatoires. En effet ces variable ne sont en lecteur seul que si elles sont une valeurs.
<!ATTLIST variable test CDATA #IMPLIED>

9
doc/variables.rst Normal file
View File

@ -0,0 +1,9 @@
Variables
=========
La balise variable est le conteneur de l'ensemble des familles dans laquelle on pourra placer des variables :
<?xml version='1.0' encoding='UTF-8'?>
<rougail>
<variables/>
</rougail>

View File

@ -80,6 +80,7 @@
<!ATTLIST override templating (True|False) "True"> <!ATTLIST override templating (True|False) "True">
<!ELEMENT variables (family*)> <!ELEMENT variables (family*)>
<!ELEMENT family (variable*)> <!ELEMENT family (variable*)>
<!ATTLIST family name CDATA #REQUIRED> <!ATTLIST family name CDATA #REQUIRED>
<!ATTLIST family description CDATA #IMPLIED> <!ATTLIST family description CDATA #IMPLIED>