From 9f2299ee3e8cac56c0fbb4dc749343c53f05da48 Mon Sep 17 00:00:00 2001 From: gwen Date: Tue, 6 Jan 2026 10:41:35 +0100 Subject: [PATCH] disabled / hidden --- docs/gettingstarted.rst | 2 + docs/tutorial/disabled.rst | 334 +++++++++++++++++++++++++++++++++++-- docs/tutorial/hidden.rst | 9 +- docs/tutorial/index.rst | 1 - 4 files changed, 329 insertions(+), 17 deletions(-) diff --git a/docs/gettingstarted.rst b/docs/gettingstarted.rst index e92dbbc40..9f6c7e850 100644 --- a/docs/gettingstarted.rst +++ b/docs/gettingstarted.rst @@ -1,3 +1,5 @@ +:orphan: + The variables ----------------- diff --git a/docs/tutorial/disabled.rst b/docs/tutorial/disabled.rst index fd79b1e3a..bdbffdb42 100644 --- a/docs/tutorial/disabled.rst +++ b/docs/tutorial/disabled.rst @@ -4,9 +4,16 @@ Disabling things .. objectives:: Objectives In this section we will see what a disabled variable or family is, and why it can be interesting - to assign the `disabled` property to a variable or a family. + to assign the `disabled` property to a variable or a family. We'll also learn the difference + between disabling and hiding families or variables. - We will disable a whole family here (yes, a family can disapear in the outerspace). + We will: + + - `disable` a whole family here (yes, a family can disapear in the outerspace!) + - use a new family or variable's property: the `hidden` property + - reuse a value of a variable for another variable + (in this use case we will reuse the HTTP configuration variables values for the configuration of the HTTPS). + .. prerequisites:: Prerequisites @@ -29,7 +36,8 @@ Disabling things A disabled family --------------------------------------------- -First, a definition: +Disabling and hiding are two families or variables properties. Let's begin with +defining what a property is: .. glossary:: @@ -114,7 +122,7 @@ It outputs: :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_040/config/02/output_ro.html :class: output -We can see that the Rougail CLI is warning us that the variables we are trying to assign values on are disabled. +We can see that the Rougail CLI is warning us about the variables that we are trying to assign values on which 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 @@ -319,7 +327,7 @@ 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. + :caption: The updated `manual` family in the :file:`firefox/20-manual.yml` structure file with the `https_proxy` family. .. %YAML 1.2 @@ -345,19 +353,315 @@ Here is the new :file:`20-manual.yml` file: 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 +Here is an example with different user values for handling HTTP and HTTPS: +.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_043/config/01/config.yml + :linenos: + :language: yaml + :caption: User datas in the user data file :file:`config/01/config.yml` with `use_for_https` as false + +.. + --- + proxy_mode: Manual proxy configuration + manual: + http_proxy: + address: http.proxy.net + port: 3128 + use_for_https: false + https_proxy: + address: https.proxy.net + +If we launch the Rougail CLI: + +.. raw:: html + :class: terminal + :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_043/config/01/cmd_ro.txt + +.. + rougail -m firefox/ -u yaml -yf config/01/config.yml + +We have this output: + +.. raw:: html + :class: output + :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_043/config/01/output_ro.html + +.. + 
╭────────────── Caption ───────────────╮
+    │ Variable Default value               │
+    │          Modified value              │
+    │          (⏳ Original default value) │
+    ╰──────────────────────────────────────╯
+    Variables:
+    ┣━━ 📓 proxy_mode (Configure Proxy Access to the Internet): Manual proxy 
+    ┃   configuration ◀ loaded from the YAML file "config/01/config.yml" (⏳ No 
+    ┃   proxy)
+    ┗━━ 📂 manual (Manual proxy configuration)
+        ┣━━ 📂 http_proxy (HTTP Proxy)
+        ┃   ┣━━ 📓 address (HTTP address): http.proxy.net ◀ loaded from the YAML 
+        ┃   ┃   file "config/01/config.yml"
+        ┃   ┗━━ 📓 port (HTTP Port): 3128 ◀ loaded from the YAML file 
+        ┃       "config/01/config.yml" (⏳ 8080)
+        ┣━━ 📓 use_for_https (Also use this proxy for HTTPS): false ◀ loaded from 
+        ┃   the YAML file "config/01/config.yml" (⏳ true)
+        ┗━━ 📂 https_proxy (HTTPS Proxy)
+            ┣━━ 📓 address (HTTPS address): https.proxy.net ◀ loaded from the YAML 
+            ┃   file "config/01/config.yml"
+            ┗━━ 📓 port (HTTPS Port): 8080
+
+ +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 an identical or possibly different proxy configuration for the HTTP and for the HTTPS protocols. + +Here is an example with identical HTTP and HTTPS proxy configuration: + +.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_043/config/02/config.yml + :linenos: + :language: yaml + :caption: User datas in the user data file :file:`config/02/config.yml` with `use_for_https` as true + +.. + --- + proxy_mode: Manual proxy configuration + manual: + http_proxy: + address: http.proxy.net + port: 3128 + use_for_https: true + +Let's launch the Rougail CLI: + +.. raw:: html + :class: terminal + :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_043/config/02/cmd_ro.txt + +.. + rougail -m firefox/ -u yaml -yf config/02/config.yml + +We have this output: + +.. raw:: html + :class: output + :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_043/config/02/output_ro.html + +FIXME: il y a un dans le 
+
+.. 
+    
> [!CAUTION]
+    > 
+    > - manual (Manual proxy configuration)
+    >   - https_proxy (HTTPS Proxy)
+    >     - address (HTTPS address): :stop_sign: <span style="color: #C23636">mandatory variable but is inaccessible and has no value</span>
+    

+
+We are going to see how to point HTTPS variables to HTTPS variables
+   
+A conditional hidden family
+----------------------------
+
+Now we will focus on configuring the HTTPS mode in case of `"Manual proxy configuration"` value has been chosen.
+
+.. image:: images/firefox_manual_https.png
+
+We have added two other variables for the HTTPS use only: 
+
+.. confval:: https_proxy.address
+   :type: `domainname`
+
+   This is an address setting for the manual HTTPS configuration
+
+.. confval:: https_proxy.port
+   :type: `port`
+
+   This is a port setting for the manual HTTPS configuration
+
+We have now two very similar variables, a `manual.http_proxy.address` variable and a `manual.https_proxy.address` variable
+In the same way, we have a `manual.http_proxy.port` variable and a `manual.https_proxy.port` variable.
+
+Let's introduce a new Rougail concept here:
+
+.. glossary:: 
+
+   context
+   
+       A :term:`configuration` is highly statefull and can change at any moment.
+       Sometimes somes minor changes in the :term:`user datas ` may involve chain reactions 
+       in the whole :term:`configuration`.
+       The **context** is the state of the user datas at one moment, the set of the values of the variables
+       at a given moment. This term also refers to the ability of a system to handle 
+       the *statefull* state of a configuration. 
+       It expresses the transition between one situation to another situation, 
+       that is, the deeply **statefull** aspects of a data set.
+
+
+.. type-along:: A new variable which has the `boolean` type
+
+The best way to reproduce the `"Also use this HTTP proxy variables for HTTPS"` checkbox in the firefox interface
+is to add a boolean variable in our structure. A boolean variable can reproduce this binary choice option.
+
+Do we want to reuse, for the HTTPS mode, the same configuration as for the HTTP mode?
+Well, it depends on the :term:`context`. 
+
+We have added a new variable, named `use_for_https` here:
+
+.. confval:: use_for_https
+   :type: `boolean`
+   :default: `true`
+
+   This is a setting that enables to reuse or not the HTTP proxy configuration for HTTPS
+
+.. questions:: Question: how does it work? 
+
+   How will this variable drive the reuse of HTTP data to HTTPS data?
+
+With this :confval:`use_for_https` boolean variable, there are two possibilities, and only two: 
+
+- The http proxy's configuration will be reused for the https proxy's configuration
+- The http proxy's will not be reused for the https proxy's configuration
+
+.. questions:: Question: shall we use the `disabled` property here?
+
+   Is it relevant to use the :term:`disabled property ` here? 
+   
+   **answer**: No! Because we *need* to use these variables at any :term:`context` of the proxy's manual configuration use case, 
+   we simply have to point their values ​​in one direction or another depending on this or that context,
+   that's why it is absolutely not a question of deactivating them. The `manual.https_proxy.address` 
+   and the `manual.http_proxy.port` variables shall not be disabled (deactivated) in the manual mode. 
+
+Let's introduce a new concept here:
+
+.. glossary:: 
+
+   hidden
+   
+       A variable or family's property is hidden if its value **shall not be seen** in a given :term:`context`. 
+       Anyway, these variables can be used if the context evolves. This is the main difference 
+       between the `hidden` and the `disabled` properties (with the `disabled` property, the variables are *deactivated*.
+
+Now we can set a `hidden` property to the `https_proxy` family:
+
+Here is our new :file:`20-manual.yml` structure file:
+
+.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_043/firefox/20-manual.yml
+   :linenos:
+   :language: yaml
+   :caption: The :file:`firefox/20-manual.yml` structure file with the `hidden` property on the `https_proxy` family.
+
+We have now a `hidden` property assigned to the `https_proxy` family. 
+The variable that drives the hidden/show behavior is the `use_for_https` variable because the `hidden` property has 
+a `variable` target parameter: `variable: _.use_for_https`
+
+.. prerequisites:: Reminder
+
+   The underscore and the point before the variable (`_.use_for_https`) points to the variable that lives in the parent 
+   family.
+
+Variable type and parameters type are copied with default value
+------------------------------------------------------------------
+
+.. type-along:: For those who follow the tutorial with the help of the git repository
+
+    Now you need to checkout the `v1.1_044` version::
+     
+          git switch --detach v1.1_044
+
+.. discussion:: A contextualized default value 
+
+   A contextualized default value is a default value (of a variable) that is driven by another variable.
+   This variable type and its parameters type are copied in the default value's target variable.
+
+There is something left in the https configuration mode of the proxy: 
+
+- if the use of the proxy variables for https are the same of the proxy variables for http, 
+  that is, if `use_for_https` is true, the https configuration variables are hidden, that's OK. 
+- if the use of the proxy variables for https **are not** the same of the proxy variables for http, 
+  we would like to set their default values to the http proxy variables values.
+
+The dynamic setting of a default can be achieved in this way: the default value is a pointer to another variable's value.
+Here, the defaut value of `manual.https_proxy.address` points to `manual.http_proxy.address`.
+
+This is the same thing for the default value of the `manual.https_proxy.port` variable, 
+which points to the `manual.http_proxy.port` value.
+
+We also say that the default value is *calculated*.
+
+.. glossary::
+
+   calculated
+   
+       We say that a variable's value or a default variable's value is calculated 
+       when there is a pointer which refers to another variable's value 
+       or if there is some :term:`jinja` code or a python function that calculates it. 
+
+To summarize the HTTP and HTTPS configuration in the manual use case context, 
+here are the two :file:`firefox/10-manual.yml` and :file:`firefox/20-manual.yml` structure files:
+
+.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_044/firefox/10-manual.yml
+   :linenos:
+   :language: yaml
+   :caption: The :file:`firefox/10-manual.yml` structure file with the `http_proxy` family and the `disabled` property
+
+..
+    %YAML 1.2
+    ---
+    version: 1.1
+
+    manual:
+      description: Manual proxy configuration
+      disabled:
+        variable: _.proxy_mode
+        when_not: Manual proxy configuration
+
+      http_proxy:  # HTTP Proxy
+
+        address:
+          description: HTTP address
+          type: domainname
+          params:
+            allow_ip: true
+
+        port:
+          description: HTTP Port
+          type: port
+          default: 8080
+    ...
+
+
+.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_044/firefox/20-manual.yml   
+   :linenos:
+   :language: yaml
+   :caption: The :file:`firefox/20-manual.yml` structure file with the `hidden` property on the `https_proxy` family.
+   
+..
+    %YAML 1.2
+    ---
+    version: 1.1
+
+    manual:
+
+      use_for_https: true  # Also use this proxy for HTTPS
+
+      https_proxy:
+        description: HTTPS Proxy
+        hidden:
+          variable: _.use_for_https
+
+        address:
+          description: HTTPS address
+          default:
+            variable: __.http_proxy.address
+
+        port:
+          description: HTTPS Port
+          default:
+            variable: __.http_proxy.port
+    ...
 
 
 .. keypoints:: Key points progress
@@ -369,9 +673,17 @@ A conditional hidden family
     - 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
 
+    - FIXME add the hidden steps
+
+    We have arrived at the end of the proxy's manual configuration's section.
+
     **Keywords**
     
     - We now know what a *property* is, we have seen in details the :term:`disabled` property
     - We can target a variable's value in the `disabled` property's value,
       we call it a variable based contextual disabled family
+    - The :term:`hidden` property set to a family
+    - The fact that a property can be set dynamically
+    - The conditional dependency of a `hidden` property that depends on a `boolean` variable.
+    - A calculated default value 
 
diff --git a/docs/tutorial/hidden.rst b/docs/tutorial/hidden.rst
index eb0489fd9..32c204bf8 100644
--- a/docs/tutorial/hidden.rst
+++ b/docs/tutorial/hidden.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 The `hidden` property
 =======================
 
@@ -245,8 +247,6 @@ If we choose the manual proxy configuration mode,
 Note that in this context, if we don't set a value to the `manual.http_proxy.address` mandatory variable, even if it is `hidden`, 
 Rougail will raise an error:
 
-.. todo:: Ce raw html là est sur manual.http_proxy.address et pas manual.https_proxy.address
-
 .. raw:: html
    :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_033/config/03/output_ro.html
    :class: error-box
@@ -295,9 +295,8 @@ Here is how to achieve this:
 
 Yes, it is possible to add a `variable` parameter to the `hidden` attribute.
 
-A contextualized default value
----------------------------------
-
+Variable type and parameters type are copied with default value
+------------------------------------------------------------------
 
 .. discussion:: A contextualized default value 
 
diff --git a/docs/tutorial/index.rst b/docs/tutorial/index.rst
index d1217d554..c73e6aec2 100644
--- a/docs/tutorial/index.rst
+++ b/docs/tutorial/index.rst
@@ -52,7 +52,6 @@ Let's dive into this **configuration options validation** use case.
    family
    domainname
    disabled
-   hidden
    dynfam
    calculation