update french documentation
This commit is contained in:
Emmanuel Garette
parent
0abd4398c7
commit
c24ef61bff
6 changed files with 287 additions and 7 deletions
|
|
@ -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
|
||||
|
|
|
|||
187
doc/dev/README.md
Normal file
187
doc/dev/README.md
Normal file
|
|
@ -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 :
|
||||
|
||||
```
|
||||
<?xml version='1.0' encoding='UTF-8'?>
|
||||
<rougail>
|
||||
<variables>
|
||||
<variable name="my_variable">
|
||||
<value>my_value</value>
|
||||
</variable>
|
||||
</variables>
|
||||
</rougail>
|
||||
```
|
||||
|
||||
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
|
||||
|
||||
```
|
||||
<?xml version='1.0' encoding='UTF-8'?>
|
||||
<rougail>
|
||||
<variables>
|
||||
<variable name="my_variable_extra">
|
||||
<value>my_value_extra</value>
|
||||
</variable>
|
||||
</variables>
|
||||
</rougail>
|
||||
```
|
||||
|
||||
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 :
|
||||
|
||||
```
|
||||
<?xml version='1.0' encoding='UTF-8'?>
|
||||
<rougail>
|
||||
<services>
|
||||
<service name="example">
|
||||
<file name="/etc/example.conf"/>
|
||||
</service>
|
||||
</services>
|
||||
</rougail>
|
||||
```
|
||||
|
||||
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 :
|
||||
|
||||
```
|
||||
<?xml version='1.0' encoding='UTF-8'?>
|
||||
<rougail>
|
||||
<constraints>
|
||||
<fill name="return_no">
|
||||
<target>my_variable</target>
|
||||
</fill>
|
||||
</constraints>
|
||||
</rougail>
|
||||
```
|
||||
|
||||
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".
|
||||
67
doc/dev/config.md
Normal file
67
doc/dev/config.md
Normal file
|
|
@ -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".
|
||||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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 :
|
||||
|
|
|
|||
|
|
@ -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 :
|
||||
|
||||
```
|
||||
|
|
|
|||
Loading…
Reference in a new issue