diff --git a/docs/tutorial/domainname.rst b/docs/tutorial/domainname.rst index 5d04777d1..970c41ee0 100644 --- a/docs/tutorial/domainname.rst +++ b/docs/tutorial/domainname.rst @@ -25,7 +25,7 @@ Some suitable types git clone https://forge.cloud.silique.fr/stove/rougail-tutorials.git git switch --detach v1.1_030 -.. type-along:: let's recap how far we've come +.. type-along:: Let's recap how far we've come We have an `http_proxy` family with an `address` variable in it. diff --git a/docs/tutorial/family.rst b/docs/tutorial/family.rst index 00ae7f6f1..3d4054fbc 100644 --- a/docs/tutorial/family.rst +++ b/docs/tutorial/family.rst @@ -27,7 +27,7 @@ Group variables inside families git clone https://forge.cloud.silique.fr/stove/rougail-tutorials.git git switch --detach v1.1_020 -.. type-along:: let's recap how far we've come +.. type-along:: Let's recap how far we've come We have this choice variable in its structure definition file: @@ -203,7 +203,7 @@ otherwise we will get an error if we try to access this variable: ┗━━ - manual.http_proxy.address (HTTP address) -.. type-along:: let's set user values in a user data file +.. type-along:: Let's set user values in a user data file Here is a user data file sample: @@ -248,18 +248,18 @@ Everything is OK: ┗━━ 📓 HTTP address: example.net ◀ loaded from the YAML file "config/02/config.yml" -Let's recap about the user datas. We can see in this Rougail CLI output that: +Let's recap about the user data. We can see in this Rougail CLI output that: - the `proxy_mode` value is set by default by the :term:`integrator` - the `address` value is has been set by an :term:`operator` -.. keypoints:: let's review the key points +.. 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 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** diff --git a/docs/tutorial/index.rst b/docs/tutorial/index.rst index 4748053c8..dabd37b38 100644 --- a/docs/tutorial/index.rst +++ b/docs/tutorial/index.rst @@ -20,8 +20,8 @@ More precisely, this tutorial aims at reproducing :term:`variable`\ s behind thi We'll call the variables **configuration options** since that's what the variables represent in this use case. -.. attention:: We are not coding a firefox plugin here. - We are just going to handle some of the firefox configuration settings +.. attention:: We are not coding a Firefox plugin here. + We are just going to handle some of the Firefox configuration settings with Rougail. We are just validating them. The configuration option values entered by the user have to be: @@ -36,7 +36,7 @@ Let's dive into this **configuration options validation** use case. It is advisable to follow this tutorial with the help of the corresponding :tutorial:`Rougail git repository tutorial `. You can instead copy/paste or download the different file contents that are explained in this tutorial step and save the files to your computer. - However, if you use the git rougail tutorial repository, you will have all the necessary files distributed in the correct tree structure, + However, if you use the git Rougail tutorial repository, you will have all the necessary files distributed in the correct tree structure, which is in our opinion much more practical. :: @@ -45,7 +45,7 @@ Let's dive into this **configuration options validation** use case. .. toctree:: :titlesonly: - :caption: The firefox tutorial + :caption: The Firefox tutorial preliminary choice diff --git a/docs/tutorial/preliminary.rst b/docs/tutorial/preliminary.rst index 4c0477e4f..c980e5674 100644 --- a/docs/tutorial/preliminary.rst +++ b/docs/tutorial/preliminary.rst @@ -1,14 +1,14 @@ Getting started ==================== -Presentation of the firefox configuration options +Presentation of the firefox configuration options -------------------------------------------------- At first glance we can see that we have a selection of five configuration options that we need to fill in, they are highlighted here in this screenshot: .. image:: images/firefox_01.png -We'll learn in this tutorial how to set the values of the configuration options in a clean way with the Rougail library. +We'll learn in this tutorial how to set the values of the configuration options in a clean way with the Rougail library. .. objectives:: Objectives of this section @@ -27,7 +27,7 @@ We'll learn in this tutorial how to set the values of the configuration options 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 `, + 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_003 ` in the repository: @@ -36,7 +36,7 @@ We'll learn in this tutorial how to set the values of the configuration options git clone https://forge.cloud.silique.fr/stove/rougail-tutorials.git git switch --detach v1.1_000 -Creating a structure file +Creating a structure file -------------------------- .. demo:: The folder structure @@ -51,21 +51,22 @@ Creating a structure file - First, we will create a :term:`structure file `, so let's create a :file:`00-proxy.yml` file located in the :file:`firefox` subfolder. -This is an empty Rougail :term:`structure description file: ` +This is an empty Rougail :term:`structure description file: ` .. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_000/firefox/00-proxy.yml :language: yaml :caption: An empty Rougail structure file with only the YAML header and the version number :name: RougailStructVersion -.. +.. --- version: 1.1 :tutorial:`Download this file from the rougail-tutorials git repository ` -This `version` specification is just the Rougail YAML's format version specification. -By now, we have an empty structure file with the format specification in it. +This `version` specification is just the Rougail YAML's format version specification. +YAML files are loaded using a version 1.2 file parser. It is recommended (but not mandatory) to specify this in the file header, especially for linters. +By now, we have an empty structure file with the format specification in it. Let's add our first variable ------------------------------ @@ -87,7 +88,7 @@ Here we define a variable named `proxy_mode`: :caption: A Rougail structure file with only one variable in it :name: RougailDictionaryFirstVariableName -.. +.. --- proxy_mode: @@ -100,7 +101,7 @@ Let's run the Rougail CLI utility command in a terminal: rougail -m firefox/ -Well, we notice that we have an error: +Well, we notice that we have an error: .. raw:: html :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_001/config/01/output_ro.html @@ -115,11 +116,11 @@ It's because this first defined variable is :term:`mandatory` and needs to have We can therefore deduce the fact that: -.. admonition:: Fact +.. admonition:: Fact Once defined, an option configuration :term:`value` is :term:`mandatory` by default. That is to say, it is absolutely necessary to assign a value to this variable. - + Rougail expects the `proxy_mode` configuration option's value to be set. .. glossary:: @@ -129,9 +130,9 @@ Rougail expects the `proxy_mode` configuration option's value to be set. A variable is mandatory when a value is required, that is, `None` **is not** a possible value. It **must** have a defined value. -.. seealso:: To go further, have a look at the :tiramisu:`mandatory option ` - according to the :xref:`Tiramisu ` underlyning consistency system. - You will learn that it is actually possible to disable the mandatory property behavior, +.. seealso:: To go further, have a look at the :tiramisu:`mandatory option ` + according to the :xref:`Tiramisu ` underlyning consistency system. + You will learn that it is actually possible to disable the mandatory property behavior, but you need to declare it explicitely. Describe the variable @@ -150,19 +151,19 @@ Let's add a variable's description, which is not mandatory but which is usually :caption: A Rougail structure file with a variable and a description :name: RougailStructFirstVariableDescription -.. +.. --- proxy_mode: # Configure Proxy Access to the Internet :tutorial:`Download this file from the rougail-tutorials git repository ` -You have two way to define a variable's description: +You have two way to define a variable's description: - the verbose way: .. code-block:: yaml - proxy_mode: + proxy_mode: description: Configure Proxy Access to the Internet @@ -183,8 +184,8 @@ we have this output: .. raw:: html :class: output :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_002/config/01/output_rw.html - -.. + +.. 
╭──────────────────── Caption ─────────────────────╮
     │ Undocumented but modified variable Default value │
     ╰──────────────────────────────────────────────────╯
@@ -192,11 +193,11 @@ we have this output:
     ┗━━ 📓 Configure Proxy Access to the Internet: null
-We can see here that the variable's description string "Configure Proxy Access to the Internet" is used +We can see here that the variable's description string "Configure Proxy Access to the Internet" is used to refer to the `proxy_mode` variable. .. note:: The description is used in UI tools and outputs instead of the variable name. - The goal here is to provide an explanation of the variable for the user, + The goal here is to provide an explanation of the variable for the user, not to show the technical name of the variable as defined by the :term:`integrator`. Set a default value @@ -208,16 +209,16 @@ Set a default value git switch --detach v1.1_003 -We will learn different ways to set a value, the first way is setting a *default* value. +We will learn different ways to set a value, the first way is setting a *default* value. .. glossary:: default value - A default value is a variable value that is predefined, that's why this value is placed + A default value is a variable value that is predefined, that's why this value is placed right in the structure file. -Let's add a default value to this `proxy_mode` variable. +Let's add a default value to this `proxy_mode` variable. .. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_003/firefox/00-proxy.yml :language: yaml @@ -236,7 +237,7 @@ The `proxy_mode` variable requires a value, that's why we have set a `No proxy` :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_003/config/01/output_ro.html :class: output -.. +.. 
╭─────── Caption ────────╮
     │ Variable Default value │
     ╰────────────────────────╯
@@ -244,19 +245,16 @@ The `proxy_mode` variable requires a value, that's why we have set a `No proxy`
     ┗━━ 📓 Configure Proxy Access to the Internet: No proxy
-As we have set the `proxy_mode`'s value as `No proxy` by default, +As we have set the `proxy_mode`'s value as `No proxy` by default, The chosen value is indicated in the Rougail's CLI output as the default choice. - here is the short-hand default setting and description: -.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_003/firefox/00-proxy.yml - :language: yaml - :caption: The short-hand way of setting a default value and a description +.. code-block:: yaml -.. - proxy_mode: No proxy # Configure Proxy Access to the Internet + proxy_mode: No proxy # Configure Proxy Access to the Internet -- and there is the verbose way of setting a default value: +- and there is the verbose way of setting a default value: .. code-block:: yaml @@ -264,10 +262,10 @@ The chosen value is indicated in the Rougail's CLI output as the default choice. description: Configure Proxy Access to the Internet default: No proxy -There are some other :term:`short-hand ways ` with Rougail that you may encounter +There are some other :term:`short-hand ways ` with Rougail that you may encounter as you read the Rougail's documentation and tutorial. -.. admonition:: how to set a value -- the assignment +.. 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. @@ -275,7 +273,7 @@ as you read the Rougail's documentation and tutorial. .. type-along:: The different Rougail roles and setting a variable's value -So far we have only talked about the actor that writes the :term:`structure files `\ . +So far we have only talked about the actor that writes the :term:`structure files `\ . The one who writes the structure file plays the *role* of the *integrator*. .. glossary:: @@ -297,26 +295,26 @@ Now we will talk about the one that defines the values. His role is called the o An operator in the Rougail field is the person who assigns :term:`value`\ s to the pre-defined variables, his responsabilities are to set variable values correctly. - The user :term:`value`\ s, that is the values that have been set by the operator, are of course type validated. + The user :term:`value`\ s, that is the values that have been set by the operator, are of course type validated. The type validation is driven by the definitions in the :term:`structure file `. -It is the operator's responsibility to set the user datas variables values. -The operator does not handle the structure files, -he is responsible of other files called the :term:`user data files `. +It is the operator's responsibility to set the user data variables values. +The operator does not handle the structure files, +he is responsible of other files called the :term:`user data files `. .. glossary:: - user datas + user data User datas, as opposed to structured datas, are datas that only concern the assignment of values and not the consistency of the variables between them. - The variable's values are also called **user values**. + The variable's values are also called **user values**. - The consistency field is outside of the user datas scope. + The consistency field is outside of the user data scope. The consistency is handled in the :term:`structured datas `\ 's scope. -.. important:: For now, we don't know how to disable the default `mandatory` settings, +.. important:: For now, we don't know how to disable the default `mandatory` settings, so if neither a default value nor a user value are set for a given variable, Rougail will raise an error. .. exercise:: Folder structure update @@ -329,29 +327,29 @@ he is responsible of other files called the :term:`user data files ` -The operator needs to add the `-u yaml -yf config/config.yml` options to the Rougail CLI: +The operator needs to add the `-u yaml -yf config/config.yml` options to the Rougail CLI: .. raw:: html :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_003/config/02/cmd_ro.txt :class: terminal -.. +.. rougail -m firefox/ -u yaml -yf config/02/config.yml which gives us this output: @@ -360,7 +358,7 @@ which gives us this output: :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_003/config/02/output_ro.html :class: output -.. +.. 
╭──────── Caption ────────╮
     │ Variable Modified value │
     ╰─────────────────────────╯
@@ -368,24 +366,24 @@ which gives us this output:
     ┗━━ 📓 proxy_mode: No proxy ◀ loaded from the YAML file "config/02/config.yml"
-Now the `proxy_mode`'s new `No proxy` value is the same as the default value but we see in the Rougail CLI output that the value +Now the `proxy_mode`'s new `No proxy` value is the same as the default value but we see in the Rougail CLI output 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). -.. type-along:: structure values and user data values +.. type-along:: Structure values and user data values -We can see with the Rougail CLI utility where the values come from. +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:: user data files are where the user values live +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:: User data files are where the user values live We need to set the values ​​in separate files, called `user data files`. @@ -393,19 +391,19 @@ We need to set the values ​​in separate files, called `user data files`. user data file - A user data file is a file where only :term:`user datas` are set. + A user data file is a file where only :term:`user data` are set. - A user file is a file where there are only user datas in it, users can set values, called user values -- + A user file is a file where there are only user data in it, users can set values, called user values -- that is variable's values that have been set by an :term:`operator`\ . - see also :term:`user datas` + see also :term:`user data` .. glossary:: - configuration + configuration We call configuration the whole system structure and user values, - and when we speak of consistency, it is in relation to this whole set. + and when we speak of consistency, it is in relation to this whole set. .. keypoints:: Key points progress @@ -419,4 +417,3 @@ We need to set the values ​​in separate files, called `user data files`. - a variable's user value - the :term:`integrator` and :term:`operator` roles - a :term:`configuration` -