diff --git a/docs/structfile.rst b/docs/structfile.rst index 7cc641ae6..c27e45e8d 100644 --- a/docs/structfile.rst +++ b/docs/structfile.rst @@ -55,7 +55,7 @@ The structured data structured data We sometimes call "structured datas" the datas that are defined in the structure files, - as opposed to :term:`user datas `\ . + as opposed to :term:`user datas `\ . For example when a value of a variable is defined in the structured datas, that is in a structured file, the assigned value's status is that the variable's value is a default value. If the assigned value of the variable is defined in a user data file, @@ -76,10 +76,10 @@ What contains exactly a :term:`structure file`? A :term:`structure file` is a YAML file whose structure is described in this documentation page. -A structure file contains a set of variables loaded into :term:`Tiramisu`, usable in your application, for example in a :term:`template` +A structure file contains a set of variables loaded into :term:`Tiramisu`, usable in your application, for example in a template to generate configuration files. -:term:`Families` and :term:`variables` can be defined in several structure files. These structure files are then aggregated. +:term:`Families ` and :term:`variables ` can be defined in several structure files. These structure files are then aggregated. If you want to see the contents of a structure file, you can have a look at the :ref:`tutorial with a real world sample. ` diff --git a/docs/tutorial/disabled.rst b/docs/tutorial/disabled.rst index 44e5c49a8..fd79b1e3a 100644 --- a/docs/tutorial/disabled.rst +++ b/docs/tutorial/disabled.rst @@ -67,8 +67,10 @@ Here we are going to assign the `disabled` property to the `manual` family: type: port default: 8080 +We have this `disabled: true` property assigned to the `manual` family. + .. raw:: html - :class: terminal + :class: terminal :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_040/config/01/cmd_ro.txt .. @@ -80,7 +82,8 @@ The Rougail CLI outputs this: :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_040/config/01/output_ro.html :class: output -We can deduce that the `manual` family is not taken into account by Rougail. +We can deduce from the Rougail CLI output that the `manual` family is not taken into account by Rougail. +Let's first examine what this disabled property does. .. glossary:: @@ -111,7 +114,10 @@ It outputs: :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_040/config/02/output_ro.html :class: output -Let's have a look at come back to our use case, we have a choice between five options +We can see that the Rougail CLI is warning us that the variables we are trying to assign values on are disabled. +That is to say, they are not taken into account at the :term:`configuration` level. + +If we have a closer look at our use case, we have a choice between five options in order to set the proxy mode: .. image:: images/firefox_01.png @@ -124,31 +130,37 @@ These five choices are: - Manual proxy configuration - Automatic proxy configuration URL -If the `Manual proxy configuration` is not selected, we don't need to set -the `address` and `port` variables, there is no point in setting them. +Actually if the `Manual proxy configuration` is not selected, we don't need to set +these `address` and `port` variables, there is no point in setting them in +four out of our five use cases. + We could say that we disable them in order to expose the fact that we don't use them, -but it's not just that: if we fill them in, there might be a problem in the overall integrity of the configuration. -We shall fill and use in these variables in the `Manual proxy configuration` context only. +but it's not just that: if we fill them in, there might be a problem in the overall integrity of the whole :term:`configuration`. +We shall fill and use in these variables in the `Manual proxy configuration` use case context only. Otherwise, **we need to disable them when they are not necessary**. -If we fill them in, Rougail CLI will output a warning and the :term:`operator` will wonder : "what am I doing?". -I shall fill and use in these variables only in the `Manual proxy configuration` context. +In a practical point of view, if we fill them in, Rougail CLI will output a warning and the :term:`operator` will see it. +He will wonder : "oh, what am I doing?", I shall fill and use in these variables only in the `Manual proxy configuration` context. .. important:: We need to **disable** variables or families that are not used in a given usage context. -.. type-along:: Disabling a group of variables is disabling a family +.. type-along:: Disabling variables one by one can be replaced by disabling a family -If we don't choose the manual mode, we need to **disable** these variables. +If we don't choose the manual mode, we need to **disable** the whole `manual` family, it will disable +all the subfamilies and the variables in it. Note that we've placed theses variables in the `http_proxy` -subfamily. We can then disable the whole `manual` subfamily in order to -disable the `http_proxy` family and all the variables that are placed in it. +subfamily. We can then disable it or even the parent `manual` subfamily in order to +disable the `http_proxy` family and all the variables that are placed in it, because +the `manual` family variables shall be used only in the manual proxy use case context. + +Notice the `disabled: true` parameter set in the `manual` family: .. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_040/firefox/10-manual.yml :linenos: :language: yaml - :caption: The `http_proxy` subfamily in the :file:`firefox/10-manual.yml` structure file + :caption: The `http_proxy` subfamily in the :file:`firefox/10-manual.yml` structure file is disabled here .. --- @@ -170,9 +182,6 @@ disable the `http_proxy` family and all the variables that are placed in it. type: port default: 8080 -Notice the `disabled: true` parameter set in the `manual` family. - - A conditional disabled family ------------------------------ @@ -182,15 +191,16 @@ A conditional disabled family git switch --detach v1.1_041 -What we need is a *dynamic setting* of the disable/enable property of the `manual` family. -The idea in this section is to dynamically set the enable/disable tag according to the chosen context. +What could be usefull here is a *dynamic setting* of the disable/enable property of the `manual` family. +The idea in this section is to dynamically set the enable/disable property according to the chosen use case context. + +In rougail, we can set a property's value **depending on** the value of another variable. **It is conditioned by** another variable. .. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_041/firefox/10-manual.yml :linenos: :language: yaml :caption: The :file:`firefox/10-manual.yml` structure file. The `manual` family dynamically enabled or disabled - .. %YAML 1.2 --- @@ -215,12 +225,21 @@ The idea in this section is to dynamically set the enable/disable tag according type: port default: 8080 -FIXME : trouver une autre formulation et expliquer un peu plus, notamment le "when_not" -.. note:: The `_.` Rougail's notation means the variable in the current workspace. +Now the `disabled` property has some parameter defined. First, let's explaine the `variable` parameter. +This parameter specifies the target variable. The value of this target variable +will be used to dynamically enable or disable our `manual` family. We can see here that the `manual` family disabled or enabled property is contitionned by the `_.proxy_mode` variable's value. +The target variable is `_.proxy_mode`. + +The `.` notation means the path of the family or subfamily you're currently in. +The `_.` notation means the parent path of the current family or subfamily path. + +Regarding the `when_not` parameter, it means that if the target variable's value +is `Manual proxy configuration` then the `manual` **will not** be disabled (that is, it will be enabled). + +Here as the default value for the `proxy_mode`'s variable is `No proxy`, the `manual` familiy is disabled. -As the default value for the `proxy_mode`'s variable is `No proxy`, the `manual` familiy is disabled. Let's launch the Rougail CLI on an empty user value file: @@ -234,7 +253,7 @@ Let's launch the Rougail CLI on an empty user value file: We have this output: .. raw:: html - :class: output + :class: output :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_041/config/01/output_ro.html .. @@ -249,12 +268,17 @@ We can see that the `manual` family and all the variables into it are not presen .. type-along:: Dynamically enabling the `manual` family -Now if we choose **the manual mode**, that is the `Manual proxy configuration` value for the `proxy_mode`, things become slightly different. +If the manual mode for the proxy is not selected, then the `manual` family is disabled. +On the other hand, if the manual proxy's configuration mode is selected, +then the `manual` family is re-activated (enabled). -.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_041/config/02/config.yaml +Now we are going to select the ** manual mode**, that is the `Manual proxy configuration` +value for the `proxy_mode` variable, and things will become slightly different. + +.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_041/config/02/config.yml :linenos: :language: yaml - :caption: The `proxy_mode`'s manual setting in the :file:`config/03/config.yaml` user datas file + :caption: The `proxy_mode`'s manual setting in the :file:`config/02/config.yaml` user datas file .. --- @@ -265,39 +289,85 @@ Now if we choose **the manual mode**, that is the `Manual proxy configuration` port: 3128 use_for_https: false -If the manual mode for the proxy is not selected, then the `manual` family shall be disabled. -On the other hand, if the manual proxy's configuration mode is selected, -then the `manual` family is activated (enabled). - .. note:: Remember that this activation/deactivation of the `manual` family - depends on the value of the `proxy_mode` variable. - -In rougail, we can set a property's value **depending on** the value of another variable. That is, **it is conditioned by** another variable. - -FIXME expliquer ici mieux le "when_not" + depends on the value of the `proxy_mode` variable. Here we have + chosen the `Manual proxy configuration` value. .. rubric:: Explanation -Here we have the `disabled` property like this: +Here the `disabled` property **depends on** the value of the `proxy_mode` variable. +It is the `variable` parameter that allows you to define the name of the target variable on which the `disabled` property depends. + +Copy HTTP manual proxy to HTTPS manual proxy +--------------------------------------------- + +.. type-along:: For those who follow the tutorial with the help of the git repository + + Now you need to checkout the `v1.1_042` version:: + + git switch --detach v1.1_042 + + +We have split the definition of the `manual` familiy into two specific files: + +.. raw:: html + :class: output + :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_042/tree.html + +Here is the new :file:`20-manual.yml` file: + +.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_042/firefox/20-manual.yml + :linenos: + :language: yaml + :caption: The :file:`firefox/20-manual.yml` structure file with the `https_proxy` family. + +.. + %YAML 1.2 + --- + version: 1.1 + + manual: + + use_for_https: true # Also use this proxy for HTTPS + + https_proxy: # HTTPS Proxy + + address: + description: HTTPS address + type: domainname + params: + allow_ip: true + + port: + description: HTTPS Port + type: port + default: 8080 + +This `https_proxy` family is identical to the `http_proxy` family except that it defines variables intended for the HTTPS protocol. + +Notice that we have a `use_for_https` new variable, this variable is a `boolean` type, its default value is `True`. +We want to offer the possibility of providing the same proxy configuration for the HTTP and the HTTPS requests. + +A conditional hidden family +---------------------------- + +.. type-along:: For those who follow the tutorial with the help of the git repository + + Now you need to checkout the `v1.1_043` version:: + + git switch --detach v1.1_043 -.. code-block:: yaml - disabled: - type: variable - variable: proxy_mode - when_not: 'Manual proxy configuration' -Here the `disabled` property **depends on** the value of another variable. -The `variable` parameter allows you to define the name of the target variable on which the `disabled` property depends. .. keypoints:: Key points progress **summary** - We have the ability to build a contextual setting: + We have now the ability to build a contextual setting: - - if `proxy_mode` is not `'Manual proxy configuration'` the `manual` family is disabled - - if `proxy_mode == 'Manual proxy configuration'` the `manual` family is enabled + - if the `proxy_mode` variable's value is not `'Manual proxy configuration'` the `manual` family is disabled + - if the `proxy_mode` variable's value is `'Manual proxy configuration'` then the `manual` family is enabled **Keywords** diff --git a/docs/tutorial/boolean.rst b/docs/tutorial/hidden.rst similarity index 100% rename from docs/tutorial/boolean.rst rename to docs/tutorial/hidden.rst diff --git a/docs/tutorial/index.rst b/docs/tutorial/index.rst index dabd37b38..d1217d554 100644 --- a/docs/tutorial/index.rst +++ b/docs/tutorial/index.rst @@ -52,7 +52,7 @@ Let's dive into this **configuration options validation** use case. family domainname disabled - boolean + hidden dynfam calculation diff --git a/docs/tutorial/tutorial.rst b/docs/tutorial/tutorial.rst index 16a1c0a08..93f1ac73e 100644 --- a/docs/tutorial/tutorial.rst +++ b/docs/tutorial/tutorial.rst @@ -1,52 +1,5 @@ - :orphan: -The HTTP proxy configuration ------------------------------- - -In this family let's add a *subfamily* named `http_proxy`, containing the address and port configuration variables. - -Let's create the :file:`dict/03-proxy_manual_http_proxy.yml` dictionary: - -.. code-block:: yaml - :caption: the the :file:`dict/02-proxy_manual.yml` file - :linenos: - - --- - version: '1.1' - proxy: - manual: - http_proxy: - description: HTTP Proxy - address: - description: HTTP address - type: domainname - port: - description: HTTP Port - type: port - default: '8080' - -Both variables `address` and `port` have particular types (respectively `domainname` line 9 and `port` line 12) to validate the values configured by the user. - -.. note:: No need to specify the type of the `http_proxy` as a family type, because here we have declared variables inside of it. - -Duplicating the HTTP configuration to HTTPS ---------------------------------------------- - -We then want to offer the user the possibility of providing the same proxy for the HTTPS requests. Let's create the :file:`dict/04-proxy_manual_http_use_for_https.yml` file: - -.. code-block:: yaml - :caption: the :file:`dict/04-proxy_manual_http_use_for_https.yml` file - - version: '1.1' - proxy: - manual: - use_for_https: - description: Also use this proxy for HTTPS - type: boolean - -This variable is a `boolean` type, its default value is `True`. - HTTPS proxy configuration detail -----------------------------------