From 8d47923abee4a35447719ad7b8c26fe43dcbdca8 Mon Sep 17 00:00:00 2001 From: Emmanuel Garette Date: Wed, 10 Feb 2021 08:19:33 +0100 Subject: [PATCH] fill's documentation --- doc/README.md | 12 ++- doc/check/README.md | 10 ++ doc/check/function.md | 124 ++++++++++++++++++++++ doc/fill/README.md | 3 +- doc/fill/param.md | 197 ----------------------------------- doc/fill/redefine.md | 12 ++- doc/fill/value.md | 18 ++-- doc/param/README.md | 7 ++ doc/param/information.md | 10 ++ doc/param/positional.md | 26 +++++ doc/param/simple.md | 37 +++++++ doc/param/variable.md | 55 ++++++++++ doc/service/README.md | 9 ++ doc/service/file.md | 18 ++++ doc/service/ip.md | 11 ++ doc/service/override.md | 7 ++ doc/service/port.md | 7 ++ doc/target/variable.md | 13 +++ src/rougail/data/rougail.dtd | 2 +- 19 files changed, 368 insertions(+), 210 deletions(-) create mode 100644 doc/check/README.md create mode 100644 doc/check/function.md delete mode 100644 doc/fill/param.md create mode 100644 doc/param/README.md create mode 100644 doc/param/information.md create mode 100644 doc/param/positional.md create mode 100644 doc/param/simple.md create mode 100644 doc/param/variable.md create mode 100644 doc/service/README.md create mode 100644 doc/service/file.md create mode 100644 doc/service/ip.md create mode 100644 doc/service/override.md create mode 100644 doc/service/port.md create mode 100644 doc/target/variable.md diff --git a/doc/README.md b/doc/README.md index 65017bfb..aa4bb4ca 100644 --- a/doc/README.md +++ b/doc/README.md @@ -7,7 +7,15 @@ ## Les services + - [Les services](service/README.md) + - [La gestion d'un service](service/service.md) + - [La gestion d'un fichier](service/file.md) + - [La gestion d'un fichier de service systemd](service/override.md) + - [La gestion d'un port](service/port.md) + - [La gestion d'une ip](service/ip.md) + ## Les contraintes - - [Les calcules automatiques](fill/README.md) - - [Les vérifications des valeurs](check/README.md) + - [Les calcules automatiques](fill/README.md) + - [Les vérifications des valeurs](check/README.md) + - [Les conditions](condition/README.md) diff --git a/doc/check/README.md b/doc/check/README.md new file mode 100644 index 00000000..a05c5ed4 --- /dev/null +++ b/doc/check/README.md @@ -0,0 +1,10 @@ +# Les vérifications des valeurs + + - [Fonction de vérification](function.md) + - [Cible de la fonction](../target/only_var.md) + - [Paramètre de la fonction](../param/README.md) + - [Réfinition](redefine.md) + +FIXME + + diff --git a/doc/check/function.md b/doc/check/function.md new file mode 100644 index 00000000..3f618490 --- /dev/null +++ b/doc/check/function.md @@ -0,0 +1,124 @@ +# Valeur calculée de la variable + +## Variable avec une valeur par défaut calculée + +Créons une variable dont la valeur est retournée par la fonction "return_no" : + +``` + + + + + + + + my_calculated_variable + + +``` + +Puis créons la fonction "return_no" : + +``` +def return_no(): + return 'no' +``` + +La [cible](../target/variable.md) du calcul est ici "my_calculated_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. + +Attention, si une valeur par défaut est définit dans la variable "my_calculated_variable" : + +``` + + yes + +``` +Cette valeur par défaut sera complètement ignorée. C'est le calcul qui en définira la valeur. + +Il est possible de définir des [paramètres](../param/README.md) à cette fonction. + +## 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 : + +``` + ``` - Cette valeur par défaut sera complètement ignorée. C'est le calcul qui en définira la valeur. +Il est possible de définir des [paramètres](../param/README.md) à cette fonction. + ## 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 : @@ -50,10 +55,9 @@ Une [variable suiveuse](../variable/leadership.md) ne peut pas être calculé au Une [variable meneuse](../variable/leadership.md) peut être calculé automatiquement. Si la variable n'est pas multiple, il ne faut pas que le calcule retourne une liste. - ## Variable dynamique avec une valeur calculée -Il est également possible de calculer [une variable d'une famille dynamique](family/auto.md) à partir d'une variable standard : +Il est également possible de calculer [une variable d'une famille dynamique](../family/auto.md) à partir d'une variable standard : ``` @@ -73,8 +77,9 @@ Il est également possible de calculer [une variable d'une famille dynamique](fa - + my_variable + my_calculated_variable_dyn_ ``` @@ -89,9 +94,10 @@ Dans ce cas, il faut explicitement demander la valeur du suffix dans la fonction ``` - + my_variable + my_calculated_variable_dyn_ ``` diff --git a/doc/param/README.md b/doc/param/README.md new file mode 100644 index 00000000..fc577906 --- /dev/null +++ b/doc/param/README.md @@ -0,0 +1,7 @@ +# Paramètre de la fonction + + - [Paramètre positionnel ou nommée](positional.md) + - [Type de paramètre simple](simple.md) + - [Type de paramètre "variable"](variable.md) + - [Type de paramètre "information"](information.md) + diff --git a/doc/param/information.md b/doc/param/information.md new file mode 100644 index 00000000..ad7bf1ec --- /dev/null +++ b/doc/param/information.md @@ -0,0 +1,10 @@ +# Paramètre de type information + +Le paramètre peut être la valeur est issue d'une information de la configuration. + +``` +server_name +``` + +Dans ce cas, l'information de la configuration "server_name" sera utilisé comme valeur du paramètre. +Si l'information n'existe pas, la paramètre aura la valeur "None". diff --git a/doc/param/positional.md b/doc/param/positional.md new file mode 100644 index 00000000..a7f8b2c9 --- /dev/null +++ b/doc/param/positional.md @@ -0,0 +1,26 @@ +# Paramètre positionnel + +Déclarons un paramètre positionnel : + +``` +no +``` + +Créons la fonction correspondante : + +``` +def return_value(value): + return value +``` + +La variable aura donc "no" comme valeur puisque le paramètre aura la valeur fixe "no". + +# Paramètre nommée + +Déclarons maintenant un paramètre nommée : + +``` +no +``` + +Dans ce cas la fonction return_value sera exécuté avec le paramètre nommé "valeur" dont sa valeur sera "no". diff --git a/doc/param/simple.md b/doc/param/simple.md new file mode 100644 index 00000000..ce95766d --- /dev/null +++ b/doc/param/simple.md @@ -0,0 +1,37 @@ +# Paramètre de type "texte" + +Dans l'exemple précédent : + +``` +no +``` + +Le paramètre est de type texte (ou "string"). +C'est le type par défaut pour un paramètre. + +# Paramètre de type "nombre" + +Déclarons un paramètre avec un nombre : + +``` +1 +``` + +Créons la fonction correspondante : + +``` +def return_value_with_number(value): + if value == 1: + return 'no' + return 'yes' +``` + +La variable aura donc "no" comme valeur puisque le paramètre aura la valeur fixe "1". + +# Paramètre de type "nil" + +Le paramètre peut être une valeur null (None en python) : + +``` + +``` diff --git a/doc/param/variable.md b/doc/param/variable.md new file mode 100644 index 00000000..2fa5b13c --- /dev/null +++ b/doc/param/variable.md @@ -0,0 +1,55 @@ +# Paramètre de type "variable" + +Imaginons que la variable "my_variable" pré-existe. La valeur de la variable sera utilisé comme paramètre : + +``` +my_variable +``` + +[Les variables meneuses ou suiveuses](../variable/leadership.md) peuvent être utilisé sans soucis commme paramètre. + +## Paramètre avec variable potentiellement non existante + +Suivant le contexte une variable peut exister ou ne pas exister. + +Un paramètre de type "variable" peut être "optional" : + +``` +unknow_variable +``` + +Si la variable "unknow_variable" n'existe pas, le paramètre ne sera pas passé à la fonction. + +Si maintenant on créé un nouveau dictionnaire en créant cette variable, la fonction sera exécuté avec le paramètre. + +## Paramètre avec variable potentiellement désactivée + +Si une variable est désactivé, l'utilisation de cette variable peut poser problème. + +Il est possible de ne pas générer d'erreur si une variable est désactivé en utilisant le paramètre "propertyerror" : + +``` +variable1 +``` + +Dans ce cas, si la variable est désactivé, le paramètre n'est jamais donnée à la fonction de destination. + +## Paramètre avec variable dynamique + +Il est possible de faire un calcul avec comme paramètre [une variable d'une famille dynamique](../family/auto.md) mais pour une suffix particulier. + +Par exemple : + +``` +vardynval1 +``` + +Dans ce cas, la valeur du paramètre de la fonction sera la valeur de la variable "vardyn" pour la famille ayant le suffix "val1". + +Il peut être utile de récupérer la valeur du suffix dans la fonction, pour cela il suffit de mettre un paramètre de type suffix : + +``` + +``` + +Dans l'exemple précédent la valeur de ce paramètre sera "val1". diff --git a/doc/service/README.md b/doc/service/README.md new file mode 100644 index 00000000..fbc65d2f --- /dev/null +++ b/doc/service/README.md @@ -0,0 +1,9 @@ +# Les services + + + + + + + + diff --git a/doc/service/file.md b/doc/service/file.md new file mode 100644 index 00000000..5f4b322f --- /dev/null +++ b/doc/service/file.md @@ -0,0 +1,18 @@ +# Fichier + +FIXME + + + + + + + + + + + + + + + diff --git a/doc/service/ip.md b/doc/service/ip.md new file mode 100644 index 00000000..c0bb61f1 --- /dev/null +++ b/doc/service/ip.md @@ -0,0 +1,11 @@ +# IP + +FIXME + + + + + + + + diff --git a/doc/service/override.md b/doc/service/override.md new file mode 100644 index 00000000..e276eb55 --- /dev/null +++ b/doc/service/override.md @@ -0,0 +1,7 @@ +# Override + +FIXME + + + + diff --git a/doc/service/port.md b/doc/service/port.md new file mode 100644 index 00000000..471e7fba --- /dev/null +++ b/doc/service/port.md @@ -0,0 +1,7 @@ +# Port + + + + + + diff --git a/doc/target/variable.md b/doc/target/variable.md new file mode 100644 index 00000000..1fd60b1e --- /dev/null +++ b/doc/target/variable.md @@ -0,0 +1,13 @@ +# Cible de la fonction de type "variable" + +Par défaut une cible est de type variable. + +``` +my_variable +``` + +Mais une target peut être optionnelle. C'est à dire que si la variable n'existe pas, l'action ne sera pas associé à cette variable. + +``` +my_variable +``` diff --git a/src/rougail/data/rougail.dtd b/src/rougail/data/rougail.dtd index 8cf5a2d4..42f84961 100644 --- a/src/rougail/data/rougail.dtd +++ b/src/rougail/data/rougail.dtd @@ -45,7 +45,7 @@ - +