From c24ef61bff3735a7a8402a1808cfd6818ffc8a73 Mon Sep 17 00:00:00 2001 From: Emmanuel Garette Date: Sun, 14 Feb 2021 10:12:42 +0100 Subject: [PATCH] update french documentation --- doc/README.md | 28 ++++-- doc/dev/README.md | 187 ++++++++++++++++++++++++++++++++++++++++ doc/dev/config.md | 67 ++++++++++++++ doc/service/ip.md | 6 +- doc/service/override.md | 2 + doc/service/port.md | 4 +- 6 files changed, 287 insertions(+), 7 deletions(-) create mode 100644 doc/dev/README.md create mode 100644 doc/dev/config.md diff --git a/doc/README.md b/doc/README.md index 7289514c1..293f91b94 100644 --- a/doc/README.md +++ b/doc/README.md @@ -1,24 +1,42 @@ # Rougail +Rougail est un bibliothèque python3 qui permet de charger des dictionnaires (fichiers au format XML), de charger les variables dans Tiramisu et de générer des templates. + +## La bibliothèque + + - [Utiliser la bibliothèque](dev/README.md) + - [Personnaliser la configration de la bibliothèque](dev/config.md) + ## Les dictionnaires -FIXME : explications -FIXME : extra +Un dictionnaire est un fichier XML donc la structure est expliqué ci-dessous. -## Les variables +Un dictionnaire contient en ensemble de variable, utilisable à tout moment, notamment dans des templates. + +Il est possible d'avoir plusieurs espace de nom pour classer les variables (appeler aussi "extra") mais il est aussi possible, à l'interieur de ce espace de nom de mettre des familles pour classer les variables. + +Les familles et les variables peuvent être défini dans plusieurs dictionnaires. Ces dictionnaires s'aggrège alors. Il est possible de rajouter des familles des variables, des services, des éléments à un service et des contraintes. + +Il est également possible de redéfinir des éléments pour changer les comportement d'une variable ou d'un service. + +### Les variables - [Les familles](family/README.md) - [Les variables](variable/README.md) -## Les services +### Les services - [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 contraintes - [Les calcules automatiques](fill/README.md) - [Les vérifications des valeurs](check/README.md) - [Les conditions](condition/README.md) + +## Les templates + + - Type creole diff --git a/doc/dev/README.md b/doc/dev/README.md new file mode 100644 index 000000000..b6fbcbd5d --- /dev/null +++ b/doc/dev/README.md @@ -0,0 +1,187 @@ +# La bibliothèque rougail + +Rougail est une bibliothèque simple a utiliser. + +Dans les exemples suivant, nous utilisons la configuration par défaut de Rougail. Vous pouvez [personnaliser les répertoires utilisés](config.md). + +## Convertisons un dictionnaire en objet tiramisu + +Commençons par créer un dictionnaire simple. + +Voici un premier dictionnaire /srv/rougail/dictionaries/00-base.xml : + +``` + + + + + my_value + + + +``` + +Construisons les objets tiramisu : + +``` +from rougail import RougailConvert + +rougail = RougailConvert() +rougail.save('example1.py') +``` + +Un nouveau fichier 'example1.py' va être créé dans le répertoire local + +## Convertisons un dictionnaire et un dictionnaire extra en objet tiramisu + +En plus du dictionnaire précédent, créons un dictionnaire extra /srv/rougail/extra_dictionaries/00-base.xml + +``` + + + + + my_value_extra + + + +``` + +Construisons les objets tiramisu : + +``` +from rougail import RougailConvert, RougailConfig + +RougailConfig['extra_dictionaries']['example'] = ['/srv/rougail/extra_dictionaries/'] + +rougail = RougailConvert() +rougail.save('example2.py') +``` + +## Templatisons un template + +Nous créons un dictionnaire complémentaire pour ajouter notre template /srv/rougail/dictionaries/00-template.xml : + +``` + + + + + + + + +``` + +Et un template /srv/rougail/templates/example.conf : + +``` +The value: %%my_variable + +The extra value: %%example.my_variable_extra +``` + +Générons le fichier tiramisu : + +``` +from rougail import RougailConvert, RougailConfig + +RougailConfig['extra_dictionaries']['example'] = ['/srv/rougail/extra_dictionaries/'] + +rougail = RougailConvert() +rougail.save('example3.py') +``` + +Créer les répertoires utils pour la templatisation : mkdir /srv/rougail/destinations /srv/rougail/tmp + +Générons le template : + +``` +import asyncio +from tiramisu import Config +from rougail import RougailTemplate +from example3 import option_0 + +async def template(): + config = await Config(option_0) + engine = RougailTemplate(config) + await engine.instance_files() + +loop = asyncio.get_event_loop() +loop.run_until_complete(template()) +loop.close() +``` + +Le fichier /srv/rougail/destinations/etc/example.conf est maintenant créé avec le contenu attendu suivant : + +``` +The value: my_value + +The extra value: my_value_extra +``` + +## Appliquons un patch au template + +Il peut être intéressant de réaliser un patch à un template pour corriger un problème spécifique à notre environnement, sans attendre que le mainteneur du template n'est fait la correction. + +Testons en créant le patch /srv/rougail/patches/example.conf.patch : + +``` +--- /srv/rougail/templates/example.conf 2021-02-13 19:41:38.677491087 +0100 ++++ tmp/example.conf 2021-02-13 20:12:55.525089820 +0100 +@@ -1,3 +1,5 @@ + The value: %%my_variable + + The extra value: %%example.my_variable_extra ++ ++Add by a patch +``` + +Le patch est bien appliquer sur notre fichier /srv/rougail/destinations/etc/example.conf : + +``` +The value: my_value + +The extra value: my_value_extra + +Add by a patch +``` + +Deux choses importantes à savoir sur les patchs : + +- le nom du patch est obligatoire le nom du template source + ".patch" +- la deuxième ligne toujours commencer par "+++ tmp/" + le nom du template source + +## Créons une fonction personnalisé + +Nous créons un dictionnaire complémentaire pour ajouter un calcul à la variable my_variable_extra dans /srv/rougail/dictionaries/00-fill.xml : + +``` + + + + + my_variable + + + +``` + +Puis créons la fonction "return_no" dans /srv/rougail/functions.py : + +``` +def return_no(): + return 'no' +``` + +Après avoir reconverti les dictionnaires et regénérer le template nous avons donc le contenu du fichier /srv/rougail/destinations/etc/example.conf : + +``` +The value: no + +The extra value: my_value_extra + +Add by a patch +``` + +La valeur de la variable my_variable est bien calculé à partir de la fonction "return_no". diff --git a/doc/dev/config.md b/doc/dev/config.md new file mode 100644 index 000000000..1143c82b3 --- /dev/null +++ b/doc/dev/config.md @@ -0,0 +1,67 @@ +# Personnalisons la configuration de Rougail + +La configuration de rougail se trouve dans l'objet RougailConfig : + +``` +from rougail import RougailConfig +``` + +C'est un simple dictionnaire python avec différentes clefs. + +Pour modifier il suffit de faire : + +``` +RougailConfig[key] = value +``` + +## Les répertoires des dictionnaires + +Il existe deux types de répertoires de dictionnaires : + +- les dictionnaires principaux avec la clef "dictionaries_dir". La valeur par défaut est ['/srv/rougail/dictionaries']. Cette variable doit contenir la liste des répertoires contenants des dictionnaires. + +Les dictionnaires sont chargés dans l'ordre des répertoires. Chaque répertoire est chargé les uns après les autres. A l'intérieur de ces répertoires les fichiers XML seront classés par ordre alphabétique. + +Il n'y a pas de classement par ordre alphabétique de l'ensemble des fichiers XML de tous les répertoires. + +Les familles et variable de ces dictionnaires sont classés, par défaut, dans l'espace de nom "rougail". Il est possible de changer le nom de cet espace de nom avec la clef "variable_namespace". + +- les dictionnaires extra avec la clef "extra_dictionaries". La valeur est un dictionnaire avec l'ensemble des espaces de nom de extra. La clef étant l'espace de nom et la valeur étant une liste de répertoire. + +Par exemple pour ajouter l'extra "example" il faut faire : + +``` +RougailConfig['extra_dictionaries']['example'] = ['/dir1', '/dir2'] +``` + +Les dictionnaires sont chargés dans le même ordre que les dictionnaires principaux. + +## La DTD + +Rougail a besoin du fichier de DTD pour lire les fichiers dictionnaire. + +Par défaut le fichier de la DTD est dans le sous répertoire "data" du répertoire de code. Le nom du fichier est rougail.dtd. + +Pour pouvez changer le répertoire de destination de la DTD et le nom du fichier avec la clef "dtdfilename". + +## Le fichier de fonction + +Le fichier qui contient les fonctions personnalisés est géré dans la clef "functions_file" et a comme valeur par défaut "/srv/rougail/functions.py". + +## Le répertoire des templates + +Le répertoire des templates est géré dans la clef "templates_dir" et a comme valeur par défaut : "/srv/rougail/templates". + +## Le répertoire des patchs + +Le répertoire des patches est géré dans la clef "patches_dir" et a comme valeur par défaut : "/srv/rougail/patches". + +## Le répertoire temporaire + +Le répertoire temporaire est utile lors de la génération de template. Il contient une copie des templates avec, éventuellement, les patches appliqués sur les templates. + +Le répertoire de temporaire est géré dans la clef "tmp_dir" et a comme valeur par défaut : "/srv/rougail/tmp". + +## Le répertoire de destination des fichiers générés + +Le répertoire de destination des fichiers générés est géré dans la clef "destinations_dir" et a comme valeur par défaut : "/srv/rougail/destinations". diff --git a/doc/service/ip.md b/doc/service/ip.md index c0bb61f16..e78cd14bc 100644 --- a/doc/service/ip.md +++ b/doc/service/ip.md @@ -1,4 +1,8 @@ -# IP +# La gestion d'une IP + +## La balise ip + +La gestion des IP se fait dans un conteneur de [service](service.md). FIXME diff --git a/doc/service/override.md b/doc/service/override.md index d071982a4..9705714da 100644 --- a/doc/service/override.md +++ b/doc/service/override.md @@ -2,6 +2,8 @@ ## La balise override +La gestion des overrides se fait dans un conteneur de [service](service.md). + La balise override permet de redéfinir facilement un service systemd. Il suffit d'avoir un template dont le nom est par défaut le nom du service avec l'extension "service" et de déclarer la balise : diff --git a/doc/service/port.md b/doc/service/port.md index 0dc7f8401..1b02d3884 100644 --- a/doc/service/port.md +++ b/doc/service/port.md @@ -1,7 +1,9 @@ -# Port +# La gestion d'un port ## La balise port +La gestion des ports se fait dans un conteneur de [service](service.md). + La balise port permet d'associer un port à service : ```