stove/rougail
3
0
Fork 0
Code Issues 10 Pull requests 1 Projects Releases Wiki Activity

update documentation

Browse source
This commit is contained in:
egarette@silique.fr 2022-11-10 22:58:24 +01:00
parent 7e38b4d952
commit 49870c1d31
12 changed files with 307 additions and 159 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

9
README.md
View file

@ -34,21 +34,21 @@ services:
- service: - service:
- name: my_service - name: my_service
file: file:
- engine: jinja2 - engine: jinja
text: /etc/filename text: /etc/filename
# describe a variable my_first_variable # describe a variable my_first_variable
# and a family with a variable my_second_variable # and a family with a variable my_second_variable
variables: variables:
- variable: - variable:
name: my_first_variable - name: my_first_variable
value: value:
- text: my_value - text: my_value
- family: - family:
name: my_family - name: my_family
variables: variables:
- variable: - variable:
name: my_second_variable - name: my_second_variable
type: number type: number
mandatory: true mandatory: true
value: value:
@ -82,7 +82,6 @@ async def main():
rougail = Rougail() rougail = Rougail()
await rougail.template() await rougail.template()
run(main()) run(main())
``` ```

5
doc/README.md
View file

@ -34,6 +34,5 @@ Rougail est un bibliothèque python3 qui permet de charger des dictionnaires (fi
## Les templates ## Les templates
- Type creole - [Les moteurs de templates](template/README.md)
- Type jinja2 - [Les patches](template/patch.md)
FIXME ^^

252
doc/dev/README.md
View file

@ -1,79 +1,130 @@
# La bibliothèque rougail # La bibliothèque Rougail
Rougail est une bibliothèque simple a utiliser. Rougail est une bibliothèque qui permet de charger simplement des dictionnaires et de générer des templates.
Dans les exemples suivant, nous utilisons la configuration par défaut de Rougail. Vous pouvez [personnaliser les répertoires utilisés](config.md). Dans les exemples suivant, nous utiliserons une configuration particulière de Rougail.
Vous retrouverez toutes les options pour [personnaliser les répertoires utilisés](config.md).
## Convertisons un dictionnaire en objet tiramisu Le script contiendra donc les éléments de configuration suivant :
Commençons par créer un dictionnaire simple.
Voici un premier dictionnaire /srv/rougail/dictionaries/00-base.xml :
```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 :
```python ```python
from rougail import RougailConvert from rougail import RougailConfig
rougail = RougailConvert() RougailConfig['dictionaries_dir'] = ['dict']
rougail.save('example.py') RougailConfig['templates_dir'] = ['tmpl']
RougailConfig['tmp_dir'] = 'tmp'
RougailConfig['destinations_dir'] = 'dest'
RougailConfig['functions_file'] = 'funcs/functions.py'
``` ```
Un nouveau fichier 'example.py' va être créé dans le répertoire local Penser a créer les répertoires :
## Convertisons un dictionnaire extra en objet tiramisu ```bash
mkdir dest dict tmp tmpl extras
```
En plus du dictionnaire précédent, créons un dictionnaire extra /srv/rougail/extra_dictionaries/00-base.xml ## Convertisons un dictionnaire
Un dictionnaire est un ensemble d'instruction qui vont permettre de créer des variables.
Commençons par créer un [dictionnaire](../dictionary/rougail.md) simple.
Voici un premier dictionnaire dict/00-base.yml :
```xml ```xml
<?xml version='1.0' encoding='UTF-8'?> version: '0.10'
<rougail> variables:
<variables> - variable:
<variable name="my_variable_extra"> - name: my_variable
<value>my_value_extra</value> value:
</variable> - text: my_value
</variables>
</rougail>
``` ```
Construisons les objets tiramisu : Puis, créons les objets [Tiramisu](https://framagit.org/tiramisu/tiramisu) :
```python ```python
from rougail import RougailConvert, RougailConfig from rougail import Rougail, RougailConfig
from asyncio import run
RougailConfig['extra_dictionaries']['example'] = ['/srv/rougail/extra_dictionaries/'] async def main():
RougailConfig['dictionaries_dir'] = ['dict']
rougail = Rougail()
config = await rougail.get_config()
print(await config.value.dict())
rougail = RougailConvert() run(main())
rougail.save('example.py')
``` ```
## Templatisons un template Exécution le script :
Nous créons un dictionnaire complémentaire pour ajouter notre template /srv/rougail/dictionaries/00-template.xml : ```python
$ python3 script.py
{'rougail.my_variable': 'my_value'}
```
## Convertisons un dictionnaire extra
L'espace de nommage par défaut des variables et familles est "rougail". Il est possible de définir d'autres espaces de nom.
Ces espaces de nom additionnels s'appelle des "[extras](../dictionary/extra.md)".
Les espaces de nom additionnels se définissent lors de la configuration.
Par exemple, voici comment ajouter une espace de nom "example" :
```python
RougailConfig['extra_dictionaries']['example'] = ['extras/']
```
Ensuite créons un dictionnaire extra extras/00-base.yml :
```xml ```xml
<?xml version='1.0' encoding='UTF-8'?> version: '0.10'
<rougail> variables:
<services> - variable:
<service name="example"> - name: my_variable_extra
<file name="/etc/example.conf"/> value:
</service> - text: my_value_extra
</services>
</rougail>
``` ```
Et un template /srv/rougail/templates/example.conf : Construisons les objets Tiramisu :
```python
from rougail import Rougail, RougailConfig
from asyncio import run
async def main():
RougailConfig['dictionaries_dir'] = ['dict']
RougailConfig['extra_dictionaries']['example'] = ['extras/']
rougail = Rougail()
config = await rougail.get_config()
print(await config.value.dict())
run(main())
```
Exécution le script :
```python
$ python3 script.py
{'rougail.my_variable': 'my_value', 'example.my_variable_extra': 'my_value_extra'}
```
## Templatisons un fichier
Un template est un fichier dans laquelle on va remplacer les valeurs attendus par le nom des variables.
Premièrement déclarons dans un dictionnaire complémentaire notre template dict/00-template.yml :
```xml
version: '0.10'
services:
- service:
- name: test
file:
- text: /etc/example.conf
```
Et un template tmpl/example.conf (par défaut il est généré via une configuration particulière de [CheetahTemplate](https://cheetahtemplate.org/) :
``` ```
The value: %%my_variable The value: %%my_variable
@ -81,42 +132,27 @@ The value: %%my_variable
The extra value: %%example.my_variable_extra The extra value: %%example.my_variable_extra
``` ```
Générons le fichier tiramisu :
```python
from rougail import RougailConvert, RougailConfig
RougailConfig['extra_dictionaries']['example'] = ['/srv/rougail/extra_dictionaries/']
rougail = RougailConvert()
rougail.save('example.py')
```
Créer les répertoires utils pour la templatisation :
```bash
mkdir /srv/rougail/destinations /srv/rougail/tmp
```
Générons le template : Générons le template :
```python ```python
import asyncio from rougail import Rougail, RougailConfig
from example import option_0 from asyncio import run
from tiramisu import Config
from rougail import RougailSystemdTemplate
async def template(): async def main():
config = await Config(option_0) RougailConfig['dictionaries_dir'] = ['dict']
engine = RougailSystemdTemplate(config) RougailConfig['templates_dir'] = ['tmpl']
await engine.instance_files() RougailConfig['tmp_dir'] = 'tmp'
RougailConfig['destinations_dir'] = 'dest'
RougailConfig['extra_dictionaries']['example'] = ['extras/']
RougailConfig['functions_file'] = 'funcs/functions.py'
rougail = Rougail()
config = await rougail.get_config()
await rougail.template()
loop = asyncio.get_event_loop() run(main())
loop.run_until_complete(template())
loop.close()
``` ```
Le fichier /srv/rougail/destinations/etc/example.conf est maintenant créé avec le contenu attendu suivant : Le fichier dest/etc/example.conf est maintenant créé avec le contenu attendu suivant :
``` ```
The value: my_value The value: my_value
@ -124,68 +160,32 @@ The value: my_value
The extra value: my_value_extra 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 :
```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 doit toujours commencer par "+++ tmp/" + le nom du template source
## Créons une fonction personnalisé ## Créons une fonction personnalisé
Nous créons un dictionnaire complémentaire pour ajouter un calcul à la variable "my_variable" dans /srv/rougail/dictionaries/00-fill.xml : Nous créons un dictionnaire complémentaire pour ajouter un calcul à la variable "my_variable" dans dict/00-fill.yml :
```xml ```yml
<?xml version='1.0' encoding='UTF-8'?> version: '0.10'
<rougail> constraints:
<constraints> - fill:
<fill name="return_no"> - name: return_no
<target>my_variable</target> target:
</fill> - text: my_variable
</constraints>
</rougail>
``` ```
Puis créons la fonction "return_no" dans /srv/rougail/functions.py : Puis créons la fonction "return_no" dans functions.py :
```python ```python
def return_no(): def return_no():
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 : Après avoir reconverti les dictionnaires et regénérer le template nous avons donc le contenu du fichier dest/etc/example.conf :
``` ```
The value: no The value: no
The extra value: my_value_extra 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". La valeur de la variable "my_variable" est bien calculé à partir de la fonction "return_no".

4
doc/dev/config.md
View file

@ -111,7 +111,7 @@ Le répertoire où se trouve les fichiers tmpfile.d sont par défaut dans "/usr/
### Le moteur de templates par défaut ### Le moteur de templates par défaut
Le moteur de template est géré dans la clef "default_files_engine" et a comme valeur par défaut : "creole". Les valeurs possible sont "none", "creole" ou "jinja2". Le moteur de template est géré dans la clef "default_files_engine" et a comme valeur par défaut : "cheetah". Les valeurs possible sont "none", "cheetah" ou "jinja".
### Les droits par défaut des fichiers ### Les droits par défaut des fichiers
@ -129,4 +129,4 @@ La méthode d'inclusion des fichiers générés est géré dans la clef "default
## La configuration du moteur de templates ## La configuration du moteur de templates
Le moteur de template est géré dans la clef "default_overrides_engine" et a comme valeur par défaut : "creole". Les valeurs possible sont "none", "creole" ou "jinja2". Le moteur de template est géré dans la clef "default_overrides_engine" et a comme valeur par défaut : "cheetah". Les valeurs possible sont "none", "cheetah" ou "jinja".

12
doc/dictionary/convention.md
View file

@ -8,6 +8,14 @@ L'ordre des informations mise dans le dictionnaire est idéalement :
- variables - variables
- constraintes - constraintes
## Le nom d'espace ## Nom des fichiers de dictionnaire
Le nom d'espace dans un dictionnaire est de deux espaces. L'ordre des dictionnaires est important pour l'ordre de création des variables et des familles.
Les fichiers devront donc démarrés par deux numéros suivit d'un tiret.
Par exemple : 00-base.xml
## Le nombre d'espace XML
Le nombre d'espace dans un dictionnaire au format XML est de deux espaces.

8
doc/service/README.md
View file

@ -70,11 +70,11 @@ Dans ce cas, il est possible de créé un template, dont le nom est obligatoirem
Deux types de template sont aujourd'hui disponible : Deux types de template sont aujourd'hui disponible :
- creole - cheetah
- jinja2 - jinja
```xml ```xml
<service name="dev-disk-by\x2dpartlabel-swap" type="swap" engine="creole"/> <service name="dev-disk-by\x2dpartlabel-swap" type="swap" engine="cheetah"/>
``` ```
En YAML : En YAML :
@ -83,7 +83,7 @@ En YAML :
- service: - service:
- name: dev-disk-by\x2dpartlabel-swap - name: dev-disk-by\x2dpartlabel-swap
type: swap type: swap
engine: creole engine: cheetah
``` ```
Dans ce cas, rougail utilisera le template "dev-disk-by\x2dpartlabel-swap.swap" pour générer le fichier systemd de gestion de ce service. Dans ce cas, rougail utilisera le template "dev-disk-by\x2dpartlabel-swap.swap" pour générer le fichier systemd de gestion de ce service.

8
doc/service/file.md
View file

@ -275,7 +275,7 @@ file:
## Choix du moteur de templating ## Choix du moteur de templating
Par défaut, le moteur de templating est le moteur de templating compatible avec "creole". Par défaut, le moteur de templating est le moteur de templating compatible avec "cheetah".
Il est possible de désactiver la templatisation du fichier (il sera alors uniquement copié) : Il est possible de désactiver la templatisation du fichier (il sera alors uniquement copié) :
@ -291,17 +291,17 @@ file:
text: /etc/squid/squid.conf text: /etc/squid/squid.conf
``` ```
Ou d'utiliser le moteur "jinja2" : Ou d'utiliser le moteur "jinja" :
```xml ```xml
<file engine="jinja2">/etc/squid/squid.conf</file> <file engine="jinja">/etc/squid/squid.conf</file>
``` ```
En YAML : En YAML :
```yml ```yml
file: file:
- engine: jinja2 - engine: jinja
text: /etc/squid/squid.conf text: /etc/squid/squid.conf
``` ```

8
doc/service/override.md
View file

@ -44,7 +44,7 @@ Dans ce cas le fichier de destination aura le même nom.
## Choix du moteur de templating ## Choix du moteur de templating
Par défaut, le moteur de templating est le moteur de templating compatible avec "creole". Par défaut, le moteur de templating est le moteur de templating compatible avec "cheetah".
Il est possible de désactiver la templatisation du fichier (il sera alors uniquement copié) : Il est possible de désactiver la templatisation du fichier (il sera alors uniquement copié) :
@ -59,17 +59,17 @@ override:
- engine: 'none' - engine: 'none'
``` ```
Ou d'utiliser le moteur "jinja2" : Ou d'utiliser le moteur "jinja" :
```xml ```xml
<override engine="jinja2"/> <override engine="jinja"/>
``` ```
En YAML : En YAML :
```yml ```yml
override: override:
- engine: 'jinja2' - engine: 'jinja'
``` ```
Il est possible de personnaliser le moteur par défaut dans la [configuration de rougail](../dev/config.md) Il est possible de personnaliser le moteur par défaut dans la [configuration de rougail](../dev/config.md)

103
doc/template/README.md vendored Normal file
View file

@ -0,0 +1,103 @@
# Les templates
## Le moteur "cheetah"
Le moteur de templating par défaut est le moteur [CheetahTemplate](https://cheetahtemplate.org/).
Par contre, la configuration par défaut de CheetahTemplate a été modifié.
Dans un template de configuration, il est très fréquent que le caractère "#" est le caractère des commentaires.
C'est pourquoi la configuration par défaut a été modifié.
Les choix sont maintenant les suivants :
- le caractère des directives : "%" ;
- les variables : "%%" ;
- le caractère des commentaires : "#".
Voici quelques exemples d'utilisateurs de ce moteur :
### utiliser une variable
```
%%variable_name
```
### condition
```
%if %%variable_name == 'oui'
text
%end if
```
### vérifier si une variable existe
```
%if %%varExists('variable_name')
text
%end if
```
### boucle
```
%for %%var in %%variable_name
%%var
%end for
```
### boucle avec variables meneuse et suiveuse
```
%for %%var in %%variable_leader
%%var.variable_follower
%end for
```
Pour plus d'informations, voir la documentation de CheetahTemplate.
## Le moteur "jinja"
Il est possible d'utiliser le moteur de templating [Jinja](https://jinja.palletsprojects.com/).
Il n'y a pas d'adaptation particulière pour ce moteur.
Voici quelques exemples d'utilisateurs de ce moteur :
### utiliser une variable
```
{{ variable_name }}
```
### condition
```
{% if variable_name == 'oui' %}
text
{% endif -%}
```
### boucle
```
{% for var in variable_name %}
{{ var }}
{% endfor -%}
```
### boucle avec variables meneuse et suiveuse
```
{% for var in variable_leader %}
{{ var.variable_follower }}
{% endfor -%}
```
Pour plus d'informations, voir la documentation de Jinja.
## Le moteur "none"
Ce moteur permet de copie le fichier sans y apporter la moindre modification.
C'est utile pour les templates ne contenant aucune variable ni condition.

39
doc/template/patch.md vendored Normal file
View file

@ -0,0 +1,39 @@
# Patcher un 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.
Par exemple le template :
```
The value: %%my_value
The extra value: %%example.my_variable_extra
```
Peut être modifié via le patch :
```patch
--- tmpl/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 fichier généré ressemblera alors à cela :
```
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 doit toujours commencer par "+++ tmp/" (tmp étant le nom du répertoire mis dans la configuration) + le nom du template source

BIN
logo.png
View file

Binary file not shown.
Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 9 KiB

After

Width:  |  Height:  |  Size: 9.1 KiB

12
logo.svg
View file

@ -81,14 +81,14 @@
<path <path
style="fill:#0f6d7c;fill-opacity:1"
d="m 255.96998,236.37088 v 150.261 h -114.977 c -45.133999,-34.582 -74.239999,-89.01 -74.239999,-150.261 z M 141.15076,386.33867"
id="path34"
sodipodi:nodetypes="cccccc" /><path
style="fill:#115d69;fill-opacity:1" style="fill:#115d69;fill-opacity:1"
d="m 255.96998,236.37088 v 150.261 h 114.977 c 45.134,-34.582 74.24,-89.01 74.24,-150.261 z M 370.7892,386.33867" d="m 255.96998,236.37088 v 150.261 l 138.67694,2.53103 c 41.40073,-52.97943 50.54006,-91.54103 50.54006,-152.79203 z"
id="path34-6" id="path34-6"
sodipodi:nodetypes="cccccc" /> sodipodi:nodetypes="ccccc" /><path
style="fill:#0f6d7c;fill-opacity:1"
d="m 255.96998,236.37088 v 150.261 l -138.67694,2.53103 C 75.892314,336.18348 66.752984,297.62187 66.752984,236.37088 Z"
id="path34-6-3"
sodipodi:nodetypes="ccccc" />

Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 5.9 KiB

After

Width:  |  Height:  |  Size: 5.8 KiB