From fe0488b8d33710eb45310a1c5c7c0ff3d5508038 Mon Sep 17 00:00:00 2001 From: Emmanuel Garette Date: Sat, 2 May 2026 19:48:40 +0200 Subject: [PATCH] fix: 08* --- caracteristique.md | 3 + docs/tutorial/customtype.rst | 546 ++++++++++++++++++----------------- docs/tutorial/family.rst | 46 +-- docs/tutorial/whatsnext.rst | 8 +- 4 files changed, 306 insertions(+), 297 deletions(-) diff --git a/caracteristique.md b/caracteristique.md index c9f615083..8fb43be7c 100644 --- a/caracteristique.md +++ b/caracteristique.md @@ -120,6 +120,9 @@ Rougail et ces composants : ### Structurals Les fichiers de "Structures" sont des fichiers au format Rougail dans laquelle toutes les informations du cycle de vie sont définies. + +Avoir des données structurées veut dire qu'on peut publier une fois et avoir plusieurs rendus. + Il est important de tout mettre ces informations au même endroit. Ainsi on connaitre toutes les aspects de la variable en lisant ces fichiers. On y retrouve : diff --git a/docs/tutorial/customtype.rst b/docs/tutorial/customtype.rst index 4c960918c..bd30f3394 100644 --- a/docs/tutorial/customtype.rst +++ b/docs/tutorial/customtype.rst @@ -3,9 +3,9 @@ Custom type .. objectives:: Objectives - In this sections we are going to learn how to create custom types with Rougail. - In short, a custom type is nothing more than a kind of a template for a family. - + In this sections we are going to learn how to create custom types with Rougail. + In short, a custom type is nothing more than a kind of a template for a variable or a family. + .. prerequisites:: Prerequisites - We assume that Rougail's library is :ref:`installed ` on your computer. @@ -15,49 +15,223 @@ Custom type Each tag corresponds to a stage of progress in the tutorial. Of course, you can also decide to copy/paste or download the tutorial files contents while following the tutorial steps. - If you want to follow this tutorial with the help of the corresponding :tutorial:`rougail-tutorials git repository `, - this workshop page corresponds to the tags :tutorial:`v1.1_080 ` to :tutorial:`v1.1_083 ` + If you want to follow this tutorial with the help of the corresponding :tutorial:`rougail-tutorials git repository `, + this workshop page corresponds to the tags :tutorial:`v1.1_080 ` to :tutorial:`v1.1_083 ` in the repository. :: - + git clone https://forge.cloud.silique.fr/stove/rougail-tutorials.git git switch --detach v1.1_080 HTTP Proxy with "proxy" type -------------------------------- -Let's look now at the possibilities for adding types. +Let's look now at the possibilities for adding types. This feature is essential for having a truly adaptable tool. -.. note:: It is actually possible to add types, - but that involves adding predefined types to the :term:`tiramisu` underlying consistency library itself, +.. note:: It is actually possible to add types, + but that involves adding predefined types to the :term:`Tiramisu` underlying consistency library itself, and that’s a different matter altogether. There is a simpler way to achieve this with the Rougail type definition feature. - -It is possible in Rougail to create custom types in a very simple way, it is much like defining families. + +It is possible in Rougail to create custom types in a very simple way, it is much like defining variables or families. Our folder structure will be expanded a bit: .. raw:: html :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_080/tree.html - + Notice that we have now a new :file:`types` folder in our tree structure. This is where we will place our new `proxy` type definition. -.. note:: Choosing the :file:`types/proxy/00-type.yml` file name is not mandatory. +.. note:: Choosing the :file:`types/proxy/00-type.yml` file name is not mandatory. You can name this folder whatever you want. - It is simply a good practice to separate structure files from type definition files. + It is simply a good practice to separate structure files from type definition files. We will see later on how to indicate to Rougail that a file contains a type declaration. In accordance with our :ref:`naming policy `, we have created a file named :file:`00-type.yml` -inside the `proxy` folder. +inside the `proxy` folder. Let's examine this more closely this :file:`types/proxy/00-type.yml` type definition file: .. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_080/types/proxy/00-type.yml - :language: yaml + :language: yaml :caption: The :file:`types/proxy/00-type.yml` type structure file that defines our new `proxy` type. - -.. + +.. + %YAML 1.2 + --- + version: 1.1 + + proxy: + + address: + description: Proxy address + type: domainname + params: + allow_ip: true + + port: + description: Proxy port + type: port + default: 8080 + ... + +The new type named `proxy` is declared the same way we declare a family. +It's more or less like a family declaration except it will be used as a type definition. +If you remember, it's mostly the content as the family `manual.http_proxy` in `firefox/10-manual.yml` file of this tutorial. + +.. questions:: How do we use a new type? + + Very simply. In the usual way: we will add a `type` parameter in our family declaration. + +Let's declare that a family is of type `proxy` as follows: + +.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_080/firefox/10-manual.yml + :language: yaml + :caption: The :file:`firefox/10-manual.yml` structure file with less code due to the `proxy` type definition + +.. + %YAML 1.2 + --- + version: 1.1 + + manual: + description: Manual proxy configuration + disabled: + variable: _.proxy_mode + when_not: Manual proxy configuration + + http_proxy: + description: HTTP Proxy + type: proxy + ... + + +We can see that the type declared for the `http_proxy` family is now `type: proxy`. +It's perfectly natural in the Rougail style. + +But in order to use our new type we need to declare it to Rougail otherwise the new type is not available. +The Rougail CLI has the `--types` type declaration command line option for this purpose. +Let's launch the Rougail CLI with this command line parameter: + +.. raw:: html + :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_080/config/01/cmd_ro.txt + :class: terminal + +The CLI output is entirely standard and does not specifically mention the call to a new type. +The result is the same as usual, as if the type declaration were omitted, which is what we want. +We want the same behavior as usual. + +.. raw:: html + :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_080/config/01/output_ro.html + :class: output + +The type definition adds nothing to the structural logic. It's just a very convenient way to save time when writing structure files. + +Now in the `address` variable it is not necessary to be specified and all parameters (the `domainname` type and the `allow_ip` parameter) are available: + +.. code-block:: yaml + :caption: We can omit these settings now due to the type definition + + description: HTTP address + type: domainname + params: + allow_ip: true + +HTTPS and SOCKS Proxy with "proxy" type +--------------------------------------- + +.. type-along:: For those who follow the tutorial with the help of the git repository + + Now you need to checkout the `v1.1_081` version:: + + git switch --detach v1.1_081 + +With this use of a type, it is possible to define our HTTPS and SOCKS Proxy in a much more conscious way: + +.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_081/firefox/20-manual.yml + :language: yaml + :caption: The :file:`firefox/20-manual.yml` structure file with less code due to the `proxy` type definition + +.. + %YAML 1.2 + --- + version: 1.1 + + manual: + + use_for_https: true # Also use this proxy for HTTPS + + https_proxy: + description: HTTPS Proxy + type: proxy + hidden: + variable: _.use_for_https + + socks_proxy: + description: SOCKS Proxy + type: proxy + ... + +Now we have two families with the `proxy` type: `https_proxy` and `socks_proxy`. + +FIXME expliqué qu'on n'a pas encore tout ce qu'on avait avant ! + +Add a variable in a family with custom type +-------------------------------------------- + +.. type-along:: For those who follow the tutorial with the help of the git repository + + Now you need to checkout the `v1.1_082` version:: + + git switch --detach v1.1_082 + + +In the `socks_proxy` family definition, we need to added a new variable, the `version` variable: + +.. code-block:: yaml + + version: + description: SOCKS host version used by proxy + choices: + - v4 + - v5 + default: v5 + +You can see that what we call a type definition in Rougail is very flexible, because it is perfectly possible +to add to what has been defined in the type. +The type definition here is therefore not only a template but much more an extensible schema. + +Redefine default value in custom type variable +----------------------------------------------- + +.. type-along:: For those who follow the tutorial with the help of the git repository + + Now you need to checkout the `v1.1_083` version:: + + git switch --detach v1.1_083 + +In this section we are going to make an implicit redefinition of variables default values. + +.. glossary:: + + redefine + + A redefine is a redefinition of all or part of the attributes of a variable as it was previously defined. + There are two types of redefine, an implicit and an explicit. + An implicit redefinition is a redefinition which has not been declared with the `redefine` attribute. + An explicit redefinition is a redefinition which has been declared with the `redefine: true` attribute. + + Only default values can be implicitly redefined (and only in the type definitions), all other attributes + need to be explicitely redefined. + +In the type definition file, we are now setting default values for the `address` and `port` variables: + +.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_083/types/proxy/00-type.yml + :language: yaml + :caption: The :file:`types/proxy/00-type.yml` type definition file with the default values for `address` and `port` + +.. %YAML 1.2 --- version: 1.1 @@ -78,19 +252,12 @@ Let's examine this more closely this :file:`types/proxy/00-type.yml` type defini default: variable: __.http_proxy.port ... - -The new type named `proxy` is declared the same way we declare a family. -It's more or less like a family declaration except it will be used as a type definition. -.. questions:: How do we use a new type? +But we don't want theses default values for HTTP definition. We can :term:`redefine` these type settings in the structure file: - Very simply. In the usual way: we will add a `type` parameter in our family declaration. - -Let's declare that a family is of type `proxy` as follows: - -.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_080/firefox/10-manual.yml - :language: yaml - :caption: The :file:`firefox/10-manual.yml` structure file with less code due to the `proxy` type definition +.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_083/firefox/10-manual.yml + :language: yaml + :caption: The :file:`firefox/10-manual.yml` structure definition file with the **redefined** default values for `address` and `port` .. %YAML 1.2 @@ -114,43 +281,57 @@ Let's declare that a family is of type `proxy` as follows: default: 8080 ... -We can see that the type declared for the `http_proxy` family is `type: proxy`. -It's perfectly natural in the rougail style. +This means that the default values for these variables will now be those defined +in the structure file if the values are defined (and not in the type definitions file). -Now in the `address` family it is not necessary to specify the `domainname` type nor the `allow_ip` parameter: +Let's have a closer look at the behavior here. -.. code-block:: yaml - :caption: We can omit these settings now due to the type definition - - description: HTTP address - type: domainname - params: - allow_ip: true - -But in order to use our new type we need to declare it to Rougail otherwise the new type is not available. -The Rougail CLI has the `--types` type declaration command line option for this purpose. -Let's launch the rougail CLI with this command line parameter: - -.. raw:: html - :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_080/config/01/cmd_ro.txt - :class: terminal - -The CLI output is entirely standard and does not specifically mention the call to a new type. -The result is the same as usual, as if the type declaration were omitted, which is what we want. -We want the same behavior as usual. +Let's launch the Rougail CLI: .. raw:: html - :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_080/config/01/output_ro.html + :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_082/config/01/cmd_ro.txt + :class: terminal + +.. + rougail -m firefox/ -u yaml -yf config/01/config.yml + +We have this output: + +.. raw:: html + :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_082/config/01/output_ro.html :class: output -The type definition adds nothing to the structural logic. It's just a very convenient way to save time when writing structure files. +We can see in the output that + +- the default values of the `port` variable, which is `8080` in the structure file, comes from the strucure file. +- the default values of the `address` variable is not set because it is `null` by default in the structure file, + so there is not such thing as a default value set for this variable. + +.. questions:: What happens if the default value in the type definition is not suitable for us? + +If we hadn't defined a value in the userdata file, the Rougail CLI would have returned the following error: + +:: + + 🛑 Caution + ┗━━ Manual proxy configuration + ┣━━ HTTP Proxy + ┃ ┗━━ Proxy address: 🛑 mandatory variable but has no value + ┗━━ SOCKS Proxy + ┗━━ Proxy address: 🛑 mandatory variable but has no value + +Therefore, the default value that was taken into account is indeed that of the structure file, and not that of the type definition. + +.. note:: We can see that the Rougail behavior is always very simple, there is no such thing as an MRO + (Method Resolution Object) that try fallback to the default value defined in the type definition file. + The Rougail behavior is much more simple and transparent. .. type-along:: kinematics of setting the `address` value Let's take the time to explain how the value of the variable `manual.http_proxy.address` is determined using the type definition. -The :file:`10-manual.yml` structure file defines the :file:`manual.https_proxy` family -which is defined with the help of the `proxy` type: +The :file:`10-manual.yml` structure file defines the :file:`manual.http_proxy` family +which is defined with the help of the `proxy` type: .. code-block:: yaml @@ -180,222 +361,38 @@ Which is `null` by default but in the :file:`config/01/config.yml` user data fil http_proxy: address: http.proxy.net -In the CLI standard output we can see that the `http_proxy.address` variable value is +In the CLI standard output we can see that the `http_proxy.address` variable value is finally set by the user data file: :: ┗━━ 📂 manual (Manual proxy configuration) ┣━━ 📂 http_proxy (HTTP Proxy) - ┃ ┣━━ 📓 address (Proxy address): http.proxy.net ◀ loaded from the YAML + ┃ ┣━━ 📓 address (Proxy address): http.proxy.net ◀ loaded from the YAML ┃ ┃ file "config/01/config.yml" - -Add a variable in a family with custom type +Redefine other parameter in custom type for HTTP -------------------------------------------------- .. type-along:: For those who follow the tutorial with the help of the git repository - Now you need to checkout the `v1.1_081` version:: - - git switch --detach v1.1_081 + Now you need to checkout the `v1.1_084` version:: -With this use of a type, it is possible to define our HTTPS and SOCKS Proxy in a much more conscious way: - -.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_081/firefox/20-manual.yml - :language: yaml - :caption: The :file:`firefox/20-manual.yml` structure file with less code due to the `proxy` type definition - -.. - %YAML 1.2 - --- - version: 1.1 - - manual: - - use_for_https: true # Also use this proxy for HTTPS - - https_proxy: - description: HTTPS Proxy - type: proxy - hidden: - variable: _.use_for_https - - socks_proxy: - description: SOCKS Proxy - type: proxy - - version: - description: SOCKS host version used by proxy - choices: - - v4 - - v5 - default: v5 - ... - -First, now we have two families with the `proxy` type: `type: proxy`, and `socks_proxy`. - -Second, in the `socks_proxy` family definition, we can see that we have added a new variable, -the `version` variable: - -.. code-block:: yaml - - version: - description: SOCKS host version used by proxy - choices: - - v4 - - v5 - default: v5 - -You can see that what we call a type definition in Rougail is very flexible, because it is perfectly possible -to add to what has been defined in the type. -The type definition here is therefore not only a template but much more an extensible schema. - -Redefine default value in custom type variable --------------------------------------------------- - -.. type-along:: For those who follow the tutorial with the help of the git repository - - Now you need to checkout the `v1.1_082` version:: - - git switch --detach v1.1_082 - -.. glossary:: - - redefine - - A redefine is a redefinition of all or part of the attributes of a variable as it was previously defined. - There are two types of redefine, an implicit and an explicit. - An implicit redefinition is a redefinition which has not been declared with the `redefine` attribute. - An explicit redefinition is a redefinition which has been declared with the `redefine: true` attribute. - - Only default values can be implicitly redefined (and only in the type definitions), all other attributes - need to be explicitely redefined. - - -In this section we are going to make an implicit redefinition of variables default values. - -In the type definition file, we have default values defined for the `address` and `port` variables: - -.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_082/types/proxy/00-type.yml - :language: yaml - :caption: The :file:`types/proxy/00-type.yml` type definition file with the default values for `address` and `port` - -.. - %YAML 1.2 - --- - version: 1.1 - - proxy: - - address: - description: Proxy address - type: domainname - params: - allow_ip: true - default: - variable: __.http_proxy.address - - port: - description: Proxy port - type: port - default: - variable: __.http_proxy.port - ... - -But we don't want theses default values. We can :term:`redefine` these type settings in the structure file: - -.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_082/firefox/10-manual.yml - :language: yaml - :caption: The :file:`firefox/10-manual.yml` structure definition file with the **redefined** default values for `address` and `port` - -.. - %YAML 1.2 - --- - version: 1.1 - - manual: - description: Manual proxy configuration - disabled: - variable: _.proxy_mode - when_not: Manual proxy configuration - - http_proxy: - description: HTTP Proxy - type: proxy - - address: - default: null - - port: - default: 8080 - ... - -This means that the default values ​​for these variables will now be those defined -in the structure file if the values are defined (and not in the type definitions file). - -Let's have a closer look at the behavior here. - -Let's launch the Rougail CLI: - -.. raw:: html - :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_082/config/01/cmd_ro.txt - :class: terminal - -.. - rougail -m firefox/ -u yaml -yf config/01/config.yml - -We have this output: - -.. raw:: html - :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_082/config/01/output_ro.html - :class: output - -We can see in the output that - -- the default values ​​of the `port` variable, which is `8080` in the structure file, comes from the strucure file. -- the default values ​​of the `address` variable is not set because it is `null` by default in the structure file, - so there is not such thing as a default value set for this variable. - -.. questions:: What happens if the default value in the type definition is not suitable for us? - -If we hadn't defined a value in the userdata file, the Rougail CLI would have returned the following error: - -:: - - 🛑 Caution - ┗━━ Manual proxy configuration - ┣━━ HTTP Proxy - ┃ ┗━━ Proxy address: 🛑 mandatory variable but has no value - ┗━━ SOCKS Proxy - ┗━━ Proxy address: 🛑 mandatory variable but has no value - -Therefore, the default value that was taken into account is indeed that of the structure file, and not that of the type definition. - -.. note:: We can see that the Rougail behavior is always very simple, there is no such thing as an MRO - (Method Resolution Object) that try fallback to the default value defined in the type definition file. - The Rougail behavior is much more simple and transparent. - -Redefine other parameter in custom type ------------------------------------------- - -.. type-along:: For those who follow the tutorial with the help of the git repository - - Now you need to checkout the `v1.1_083` version:: - - git switch --detach v1.1_083 + git switch --detach v1.1_084 In this sections we are going to make explicit :term:`redefinitions `. -The type definition didn't change, what we're talking about here is modifiying what has been previously defined -in the type definition file: +The type definition didn't change, what we're talking about here is modifiying what has been previously defined +in the type definition file: +FIXME : en fait si ! on supprime la description, de address et port qui n'a pas de sens dans le type (suivant le type il faut le redéfinir). +et on modifie ici le type pour HTTP. -.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_083/types/proxy/00-type.yml - :language: yaml +.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_084/types/proxy/00-type.yml + :language: yaml :caption: The :file:`types/proxy/00-type.yml` type definition file with the default definitions -.. +.. %YAML 1.2 --- version: 1.1 @@ -403,7 +400,6 @@ in the type definition file: proxy: address: - description: Proxy address type: domainname params: allow_ip: true @@ -411,21 +407,20 @@ in the type definition file: variable: __.http_proxy.address port: - description: Proxy port type: port default: variable: __.http_proxy.port ... -We can see here, for example, that the `address` and `port` variables don't have -any `description` atribute. We need to add one, so we need to extend the type -defintions. +We can see here, for example, that the `address` and `port` variables don't have +any `description` attribute. We need to add one, so we need to extend the type +definitions. -.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_083/firefox/10-manual.yml - :language: yaml +.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_084/firefox/10-manual.yml + :language: yaml :caption: The :file:`firefox/10-manual.yml` structure definition file with explicit redefinitions -.. +.. %YAML 1.2 --- version: 1.1 @@ -451,19 +446,18 @@ defintions. description: HTTP proxy port ... - .. note:: Transforming an implicit defintion into an explicit redefinition is very simple; you just need to add the `redefine: true` attribute: Let's launch the Rougail CLI: -.. raw:: html +.. raw:: html :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_083/config/01/cmd_ro.txt :class: terminal .. rougail -m firefox/ -u yaml -yf config/01/config.yml -We have this output: +We have this output: .. raw:: html :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_083/config/01/output_ro.html @@ -471,18 +465,18 @@ We have this output: .. Variables: - ┣━━ 📓 Configure Proxy Access to the Internet: Manual proxy configuration ◀ + ┣━━ 📓 Configure Proxy Access to the Internet: Manual proxy configuration ◀ ┃ loaded from the YAML file "config/01/config.yml" (⏳ No proxy) ┗━━ 📂 Manual proxy configuration ┣━━ 📂 HTTP Proxy - ┃ ┣━━ 📓 HTTP proxy address: http.proxy.net ◀ loaded from the YAML file + ┃ ┣━━ 📓 HTTP proxy address: http.proxy.net ◀ loaded from the YAML file ┃ ┃ "config/01/config.yml" - ┃ ┗━━ 📓 HTTP proxy port: 3128 ◀ loaded from the YAML file + ┃ ┗━━ 📓 HTTP proxy port: 3128 ◀ loaded from the YAML file ┃ "config/01/config.yml" (⏳ 8080) - ┣━━ 📓 Also use this proxy for HTTPS: false ◀ loaded from the YAML file + ┣━━ 📓 Also use this proxy for HTTPS: false ◀ loaded from the YAML file ┃ "config/01/config.yml" (⏳ true) ┣━━ 📂 HTTPS Proxy - ┃ ┣━━ 📓 HTTPS proxy address: https.proxy.net ◀ loaded from the YAML file + ┃ ┣━━ 📓 HTTPS proxy address: https.proxy.net ◀ loaded from the YAML file ┃ ┃ "config/01/config.yml" (⏳ http.proxy.net) ┃ ┗━━ 📓 HTTPS proxy port: 3128 ┗━━ 📂 SOCKS Proxy @@ -490,8 +484,8 @@ We have this output: ┣━━ 📓 SOCKS proxy port: 3128 ┗━━ 📓 SOCKS host version used by proxy: v5 -We can see in the output that the `address` and `port` variables have default values, -and descriptions ("HTTP proxy address", "HTTP proxy port") that weren't present in the +We can see in the output that the `address` and `port` variables have default values, +and descriptions ("HTTP proxy address", "HTTP proxy port") that weren't present in the type definition file. .. keypoints:: Key points @@ -502,5 +496,17 @@ type definition file. - using a type for an extended family definition - we can redefine things in the structure file and it overloads the type definition file - implicit or explicit redefinitions - + We have seen how the definition of type, used effectively, allows for a new expressiveness. + + +Redefine other parameter in custom type for HTTPS and SOCKS +----------------------------------------------------------- + +.. type-along:: For those who follow the tutorial with the help of the git repository + + Now you need to checkout the `v1.1_084` version:: + + git switch --detach v1.1_084 + +FIXME pareil pour https et socks diff --git a/docs/tutorial/family.rst b/docs/tutorial/family.rst index 1597ed0ef..b40b42085 100644 --- a/docs/tutorial/family.rst +++ b/docs/tutorial/family.rst @@ -18,12 +18,12 @@ Group variables inside families Each tag corresponds to a stage of progress in the tutorial. Of course, you can also decide to copy/paste or download the tutorial files contents while following the tutorial steps. - If you want to follow this tutorial with the help of the corresponding :tutorial:`rougail-tutorials git repository `, - this workshop page corresponds to the tags :tutorial:`v1.1_020 ` to :tutorial:`v1.1_022 ` + If you want to follow this tutorial with the help of the corresponding :tutorial:`rougail-tutorials git repository `, + this workshop page corresponds to the tags :tutorial:`v1.1_020 ` to :tutorial:`v1.1_022 ` in the repository. :: - + git clone https://forge.cloud.silique.fr/stove/rougail-tutorials.git git switch --detach v1.1_020 @@ -62,7 +62,7 @@ Now we will define new variables, and other structure definitions. For the sake of clarity, we will put the structure definitions in separate files. Please have a look at the :ref:`file naming and organizing convention `. -Here we made a :file:`firefox/00-proxy.yml` structure file and we're gonna make +Here we made a :file:`firefox/00-proxy.yml` structure file and we're gonna make a new structure file named :file:`firefox/10-manual.yml`:: . @@ -89,17 +89,17 @@ Let's create a family named `manual` which obviously corresponds to the proxy's We can see that we have defined a :term:`family` here, and this family is *empty* which means that this family is a container variable that contains no variable yet. -.. warning:: +.. warning:: If a family is empty, we need to specify the :term:`family` type here because if we don't, the Rougail's type engine will infer it by default as a :term:`variable`. - We have to force the family type inference. - - It's because we don't have set any :term:`variable` inside yet. When we will have a variable inside of this family, + We have to force the family type inference. + + It's because we don't have set any :term:`variable` inside yet. When we will have a variable inside of this family, we will make a YAML block (to create a block in YAML, you just need to indent the lines) and the Rougail's type inference engine will implicitely infer the variable's container as a family type. .. important:: - + Any family that has been declared in a structure file but is empty (i.e., contains neither :term:`variables ` nor :term:`subfamilies `) is deleted by Rougail, that is is not present in the Rougail CLI output. Or a sub family @@ -108,7 +108,7 @@ Or a sub family .. type-along:: For those who follow the tutorial with the help of the git repository Now you need to checkout the `v1.1_021` version:: - + git switch --detach v1.1_021 .. glossary:: @@ -136,7 +136,7 @@ Creating a family hierarchy of families (family inside a family) is very easy: :tutorial:`Download this file from the rougail-tutorials git repository ` -Here in our use case we used the :term:`short-hand declaration mode ` +Here in our use case we used the :term:`short-hand declaration mode ` to declare our `manual` family: .. code-block:: yaml @@ -152,7 +152,7 @@ Putting a variable inside of a family or a sub family .. type-along:: For those who follow the tutorial with the help of the git repository Now you need to checkout the `v1.1_022` version:: - + git switch --detach v1.1_022 We are going to put a variable inside of a family or a sub family @@ -194,14 +194,14 @@ We have reached the definition of the address in the `http_proxy` family; there .. type-along:: Assigning a user value -Now we need to set a value ​​for the :confval:`address` variable, +Now we need to set a value ​​for the :confval:`address` variable, otherwise we will get an error if we try to access this variable: .. raw:: html :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_022/config/01/output_ro.html :class: error-box -.. +.. 
🛑 ERRORS
     ┣━━ The following variables are mandatory but have no value:
     ┗━━   - manual.http_proxy.address (HTTP address)
@@ -209,14 +209,14 @@ otherwise we will get an error if we try to access this variable:
 
 .. type-along:: Let's set user values in a user data file
 
-Here is a user data file sample: 
+Here is a user data file sample:
 
 .. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_022/config/02/config.yml
    :language: yaml
    :caption: A user file named :file:`config/03/config.yml` with a value set for the `address` variable
    :name: RougailAddresseVariableUserValue
-       
-.. 
+   
+..
     ---
     proxy_mode: Manual proxy configuration
     manual:
@@ -231,8 +231,8 @@ Let's validate the consitency of the :term:`configuration`:
    :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_022/config/02/cmd_ro.txt
    :class: terminal
 
-.. 
-    rougail -m firefox/ -u yaml -yf config/02/config.yml   
+..
+    rougail -m firefox/ -u yaml -yf config/02/config.yml
 
 Everything is OK:
 
@@ -240,7 +240,7 @@ Everything is OK:
    :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_022/config/02/output_ro.html
    :class: output
 
-.. 
+..
     
╭──────── Caption ────────╮
     │ Variable Default value  │
     │          Modified value │
@@ -260,13 +260,13 @@ Let's recap about the user data. We can see in this Rougail CLI output that:
 .. keypoints:: Let's review the key points
 
     **Keywords**
-    
+
     - we know how to define :term:`variable`\ s inside of a family
     - we now know what a :term:`mandatory` variable is and why it is necessary to assign values to the variables
     - we kwow how to set a variable's :term:`user value `
     - we have the big picture : the :term:`configuration`, which is (the structure files + the user data files)
-    
+
     **Progress**
 
     - we have a :term:`family` named `manual`  and a sub family named `http_proxy`
-    - And we have now two variables: :confval:`proxy_mode` and :confval:`address`. 
+    - And we have now two variables: :confval:`proxy_mode` and :confval:`address`.
diff --git a/docs/tutorial/whatsnext.rst b/docs/tutorial/whatsnext.rst
index fc9826920..d96dd457e 100644
--- a/docs/tutorial/whatsnext.rst
+++ b/docs/tutorial/whatsnext.rst
@@ -3,10 +3,10 @@ To be continued
 
 **This tutorial is a work in progress!**
 
-Not all the concepts of rougail are fully explained in this tutorial. 
-You can, of course, refer to the rest of the technical documentation, or look at 
-the `tutorial's code repository  `_ 
+Not all the concepts of rougail are fully explained in this tutorial.
+You can, of course, refer to the rest of the technical documentation, or look at
+the `tutorial's code repository  `_
 and try to understand the rest of the tutorial steps on your own.
 
-.. note:: Please check again the end of the tutorial section to see if the developers 
+.. note:: Please check again the end of the tutorial section to see if the developers
           have made any progress in writing it.