From 7fc56b2429873af7ecb7b20fd4f169635a092aa5 Mon Sep 17 00:00:00 2001 From: gwen Date: Sat, 22 Nov 2025 12:24:54 +0100 Subject: [PATCH] separation of the choice --- docs/tutorial/choice.rst | 141 ++++++++++++++++++++++++++++ docs/tutorial/index.rst | 1 + docs/tutorial/preliminary.rst | 170 +++++----------------------------- docs/tutorial/proxymode.rst | 1 - 4 files changed, 164 insertions(+), 149 deletions(-) create mode 100644 docs/tutorial/choice.rst diff --git a/docs/tutorial/choice.rst b/docs/tutorial/choice.rst new file mode 100644 index 000000000..3050745e6 --- /dev/null +++ b/docs/tutorial/choice.rst @@ -0,0 +1,141 @@ +A variable with a list of possible values +========================================= + + + +.. type-along:: Defining a choice type + +In our firefox use case, the real type of the `proxy_mode` variable will be now set as a `choice` type: + +.. seealso:: Have a look at the definition of the :term:`choice type variable ` + +.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_004/firefox/00-proxy.yml + :linenos: + :language: yaml + :caption: The real :file:`firefox/proxy.yml` Rougail structure file with a choice type + :name: RougailDictionaryChoiceType + +.. + --- + proxy_mode: + description: Configure Proxy Access to the Internet + choices: + - No proxy + - Auto-detect proxy settings for this network + - Use system proxy settings + - Manual proxy configuration + - Automatic proxy configuration URL + default: No proxy + +:tutorial:`Download this file from the rougail-tutorials git repository ` + +- Let's run the Rougail CLI + +.. code-block:: text + :class: terminal + + rougail -v 1.1 -m firefox/ + +We have an output like this one: + +.. raw:: html + :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_004/config/01/output_ro.html + :class: output + +.. + 
╭────────────────────────── Caption ──────────────────────────╮
+    │ Variable                           Default value            │
+    │ Undocumented variable              Modified value           │
+    │ Undocumented but modified variable (Original default value) │
+    │ Unmodifiable variable                                       │
+    ╰─────────────────────────────────────────────────────────────╯
+    Variables:
+    ┗━━ 📓 proxy_mode: No proxy
+
+ +The `proxy_mode` variable here, implicitely requires a value. It is a :term:`mandatory` variable. + +As we set the `proxy_mode` variable as `No proxy` by default, we actually have specified a value, and the value appears in yellow, which means : "set by default". + +The constraints that come with the `choice` type +---------------------------------------------------- + +We say that the `proxy_mode` variable is *constrained* (by the `choice` type). + +.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_004/config/03/config.yml + :linenos: + :language: yaml + :caption: A user data specification + +:tutorial:`Download this file from the rougail-tutorials git repository ` + +If we run the rougail CLI with this user datas, we have: + +.. code-block:: text + :class: terminal + + rougail -m firefox -u yaml -ff config/03/config.yml + +We have this output: + +.. raw:: html + :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_004/config/03/output_ro.html + :class: output + +.. + 
╭────────────── Caption ───────────────╮
+    │ Variable Modified value              │
+    │          (⏳ Original default value) │
+    ╰──────────────────────────────────────╯
+    Variables:
+    ┗━━ 📓 Configure Proxy Access to the Internet: Manual proxy configuration ◀ loaded from the YAML file "config/03/config.yml" (⏳ No proxy)
+
+ +As we set the `proxy_mode` variable from a user data file, +we now have specified a value which is **not** a default value, +and the value appears in green, which means : "user data value". + +.. FIXME: verifier que cette sortie est bonne (on a des valeurs différentes) + +.. type-along:: The constraints that come with the `choice` property + +The `proxy_mode` variable's possible values is *constrained*. + +We have the list of the possible (authorized) values: + +- `No proxy` +- `Auto-detect proxy settings for this network` +- `Use system proxy settings` +- `Manual proxy configuration` +- `Automatic proxy configuration URL` + +.. keypoints:: Key points progress + + Indeed, in the Firefox configuration, it is possible to define several configuration modes, from no proxy at all (`no proxy`) to a kind of automatic configuration mode from a file (`set up proxy configuration from a file`). + + **Progress** + + To sum up, we have arrived at this point in writing a structure file like this: + + **Structure description file** + + .. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_004/firefox/00-proxy.yml + :linenos: + :language: yaml + :caption: A Rougail structure file with a variable named `proxy_mode`, with a default value. + +.. + + .. raw:: text + + --- + proxy_mode: + description: Configure Proxy Access to the Internet + choices: + - No proxy + - Auto-detect proxy settings for this network + - Use system proxy settings + - Manual proxy configuration + - Automatic proxy configuration URL + default: No proxy + diff --git a/docs/tutorial/index.rst b/docs/tutorial/index.rst index 97f88fe1f..fb3790eec 100644 --- a/docs/tutorial/index.rst +++ b/docs/tutorial/index.rst @@ -58,6 +58,7 @@ We'll learn in this tutorial how to set the values of the configuration options :caption: The firefox tutorial preliminary + choice proxymode disabled boolean diff --git a/docs/tutorial/preliminary.rst b/docs/tutorial/preliminary.rst index 85f9dcfb1..fe2272a6c 100644 --- a/docs/tutorial/preliminary.rst +++ b/docs/tutorial/preliminary.rst @@ -13,7 +13,7 @@ Getting started - We assume that Rougail's library is :ref:`installed ` on your computer. - 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_000 ` to :tutorial:`v1.1_011 ` + this workshop page corresponds to the tags :tutorial:`v1.1_000 ` to :tutorial:`v1.1_003 ` in the repository: :: @@ -249,21 +249,21 @@ he is responsible of other files called the :term:`user data files ` +:tutorial:`Download this file from the rougail-tutorials git repository ` With the rougail CLI the operator has to add the `-u yaml -ff config/config.yml` options: @@ -276,7 +276,7 @@ With the rougail CLI the operator has to add the `-u yaml -ff config/config.yml` which gives us this output: .. raw:: html - :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_001/config/02/output_ro.html + :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_003/config/02/output_ro.html :class: output .. @@ -287,158 +287,32 @@ which gives us this output: ┗━━ 📓 proxy_mode: No proxy ◀ loaded from the YAML file "config/02/config.yml" -.. admonition:: Important fact +Now the `proxy_mode`'s new `No proxy` value is the same as the default value but we see that the value +comes from the :file:`config/02/config.yml` user data file. From now on this `proxy_mode` variable's value +is a user data value and not a default value (even if it's actually the same value). - - the integrator works on structure files - - the operator works on user data files +.. type-along:: structure values and user data values + +We can see with the rougail CLI utility where the values come from. +It can come from an integrator's setting or from an operator's setting. + +.. admonition:: Reminder + + - the integrator works on structure files, he can define default value for variables + - the operator works on user data files, he only can set user data values for variables -Most of the time, the integrator and the operator are one and the same person, here we are talking about roles and not necessarily about people. - -.. type-along:: Defining a choice type - -In our firefox use case, the real type of the `proxy_mode` variable will be now set as a `choice` type: - -.. seealso:: Have a look at the definition of the :term:`choice type variable ` - -.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_004/firefox/00-proxy.yml - :linenos: - :language: yaml - :caption: The real :file:`firefox/proxy.yml` Rougail structure file with a choice type - :name: RougailDictionaryChoiceType - -.. - --- - proxy_mode: - description: Configure Proxy Access to the Internet - choices: - - No proxy - - Auto-detect proxy settings for this network - - Use system proxy settings - - Manual proxy configuration - - Automatic proxy configuration URL - default: No proxy - -:tutorial:`Download this file from the rougail-tutorials git repository ` - -- Let's run the Rougail CLI - -.. code-block:: text - :class: terminal - - rougail -v 1.1 -m firefox/ - -We have an output like this one: - -.. raw:: html - :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_004/config/01/output_ro.html - :class: output - -.. - 
╭────────────────────────── Caption ──────────────────────────╮
-    │ Variable                           Default value            │
-    │ Undocumented variable              Modified value           │
-    │ Undocumented but modified variable (Original default value) │
-    │ Unmodifiable variable                                       │
-    ╰─────────────────────────────────────────────────────────────╯
-    Variables:
-    ┗━━ 📓 proxy_mode: No proxy
-
- -The `proxy_mode` variable here, implicitely requires a value. It is a :term:`mandatory` variable. - -As we set the `proxy_mode` variable as `No proxy` by default, we actually have specified a value, and the value appears in yellow, which means : "set by default". - -The constraints that come with the `choice` type ----------------------------------------------------- - -We say that the `proxy_mode` variable is *constrained* (by the `choice` type). - -.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_004/config/03/config.yml - :linenos: - :language: yaml - :caption: A user data specification - -:tutorial:`Download this file from the rougail-tutorials git repository ` - -If we run the rougail CLI with this user datas, we have: - -.. code-block:: text - :class: terminal - - rougail -m firefox -u yaml -ff config/03/config.yml - -We have this output: - -.. raw:: html - :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_004/config/03/output_ro.html - :class: output - -.. - 
╭────────────── Caption ───────────────╮
-    │ Variable Modified value              │
-    │          (⏳ Original default value) │
-    ╰──────────────────────────────────────╯
-    Variables:
-    ┗━━ 📓 Configure Proxy Access to the Internet: Manual proxy configuration ◀ loaded from the YAML file "config/03/config.yml" (⏳ No proxy)
-
- -As we set the `proxy_mode` variable from a user data file, -we now have specified a value which is **not** a default value, -and the value appears in green, which means : "user data value". - -.. FIXME: verifier que cette sortie est bonne (on a des valeurs différentes) - -.. type-along:: The constraints that come with the `choice` property - -The `proxy_mode` variable's possible values is *constrained*. - -We have the list of the possible (authorized) values: - -- `No proxy` -- `Auto-detect proxy settings for this network` -- `Use system proxy settings` -- `Manual proxy configuration` -- `Automatic proxy configuration URL` +Most of the time, the integrator and the operator are one and the same person, +here we are talking about roles and not necessarily about people. .. keypoints:: Key points progress - Indeed, in the Firefox configuration, it is possible to define several configuration modes, from no proxy at all (`no proxy`) to a kind of automatic configuration mode from a file (`set up proxy configuration from a file`). - - **Keywords** - :term:`structure file `: structure description file - :term:`variable`: an option's name which has a value - a variable's description - - a variable's type + - a variable's mandatory value - a variable's default value + - a variable's user value - the :term:`integrator` and :term:`operator` roles - - a mandatory value - - a choice type - - **Progress** - - To sum up, we have arrived at this point in writing a structure file like this: - - **Structure description file** - - .. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_004/firefox/00-proxy.yml - :linenos: - :language: yaml - :caption: A Rougail structure file with a variable named `proxy_mode`, with a default value. - -.. - - .. raw:: text - - --- - proxy_mode: - description: Configure Proxy Access to the Internet - choices: - - No proxy - - Auto-detect proxy settings for this network - - Use system proxy settings - - Manual proxy configuration - - Automatic proxy configuration URL - default: No proxy diff --git a/docs/tutorial/proxymode.rst b/docs/tutorial/proxymode.rst index 3578862ce..b4451330b 100644 --- a/docs/tutorial/proxymode.rst +++ b/docs/tutorial/proxymode.rst @@ -14,7 +14,6 @@ Group variables inside families - We have an idea of what a :term:`structure description file` is - We have a folder named :file:`firefox` and we are putting all the structure description files into it - .. type-along:: let's recap: we have this choice type variable In the structure description file, we have: