diff --git a/docs/tutorial/images/proxy_choices.png b/docs/tutorial/images/proxy_choices.png new file mode 100644 index 000000000..190e9a2a0 Binary files /dev/null and b/docs/tutorial/images/proxy_choices.png differ diff --git a/docs/tutorial/preliminary.rst b/docs/tutorial/preliminary.rst index 055c0945b..686b9f349 100644 --- a/docs/tutorial/preliminary.rst +++ b/docs/tutorial/preliminary.rst @@ -190,9 +190,9 @@ Let's add a default value to this `proxy_mode` variable. .. admonition:: how to set a value -- the assignment - A default value has been set, great. This raises a question about what a normal value is. + A default value has been set, great. This raises the question of what constitutes a value other than a default value. - Now then how can I assign a normal value to a variable? + How can I assign a value to a variable? .. type-along:: The different rougail roles and the default values @@ -239,7 +239,7 @@ he is responsible of other files called the :term:`user data file`\ s. .. exercise:: Folder structure update - Now we add a :file:`config/config.yaml` file in our project:: + Now we add a :file:`config/config.yaml` file, the :file:`config` folder is where we will place the user datas:: rougail-tutorials ├── firefox @@ -261,9 +261,10 @@ it's up to the operator to do the job in the `config.yaml` file: --- proxy_mode: No proxy -:tutorial:`Download this file from the rougail-tutorials git repository ` +: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.yaml` options: +If you want the user datas to be taken into account, you must provide the `-u yaml -ff config/config.yaml` options +to the rougail CLI: .. code-block:: text :class: terminal @@ -285,6 +286,8 @@ which gives us this output: ┗━━ 📓 proxy_mode: No proxy ◀ loaded from the YAML file "config/02/config.yaml" +We can see in the output result that the :file:`config/02/config.yml` user data file has been taken into account. + .. admonition:: Important fact - the integrator works on structure files @@ -292,16 +295,26 @@ which gives us this output: 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 +Limits the possible values for the variable +------------------------------------------------- -In our firefox use case, the real type of the `proxy_mode` variable will be now set as a `choice` type: +.. type-along:: For those who follow the tutorial with the help of the git repository -.. seealso:: Have a look at the definition of the :term:`choice type variable ` + Now you need to checkout the `v1.1_004` version:: + + git checkout v1.1_004 + +In our firefox use case, we can see that we have different possibilites available for the `proxy_mode` variable values: + + +.. image:: images/proxy_choices.png + +Let's insert these different possible choices with a `choice` variable's property here: .. 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 + :caption: The real :file:`firefox/proxy.yml` Rougail structure file with different possible choices :name: RougailDictionaryChoiceType .. @@ -318,7 +331,7 @@ In our firefox use case, the real type of the `proxy_mode` variable will be now :tutorial:`Download this file from the rougail-tutorials git repository ` -- Let's run the Rougail CLI +- Let's run the Rougail CLI now: .. code-block:: text :class: terminal @@ -344,13 +357,14 @@ We have an output like this one: 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". +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 ----------------------------------------------------- +.. todo:: ajouter une sortie qui montre que la valeur provient du user data file. -We say that the `proxy_mode` variable is *constrained* (by the `choice` type). +.. 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` @@ -369,11 +383,10 @@ We have the list of the possible (authorized) values: - :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 default value - the :term:`integrator` and :term:`operator` roles - a mandatory value - - a choice type + - the possibility to constrain the possible values of a variable **Progress**