review
This commit is contained in:
parent
aabc937d1c
commit
8b02c79dcc
4 changed files with 71 additions and 74 deletions
|
|
@ -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.
|
||||
|
||||
|
|
|
|||
|
|
@ -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:
|
|||
<span style="color: #ff0000">┗━━ </span> - manual.http_proxy.address (HTTP address)
|
||||
</pre>
|
||||
|
||||
.. 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:
|
|||
<span style="color: #5c5cff"> </span><span style="color: #5c5cff"> </span><span style="color: #5c5cff">┗━━ </span>📓 HTTP address: example.net ◀ loaded from the YAML file "config/02/config.yml"
|
||||
</pre>
|
||||
|
||||
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 <user datas>`
|
||||
- we kwow how to set a variable's :term:`user value <user data>`
|
||||
- we have the big picture : the :term:`configuration`, which is (the structure files + the user data files)
|
||||
|
||||
**Progress**
|
||||
|
|
|
|||
|
|
@ -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 <src/branch/1.1>`.
|
||||
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
|
||||
|
|
|
|||
|
|
@ -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 <src/branch/1.1>`,
|
||||
If you want to follow this tutorial with the help of the corresponding :tutorial:`rougail-tutorials git repository <src/branch/1.1>`,
|
||||
this workshop page corresponds to the tags :tutorial:`v1.1_000 <src/tag/v1.1_000>` to :tutorial:`v1.1_003 <src/tag/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 <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: <structure file>`
|
||||
This is an empty Rougail :term:`structure description file: <structure 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 <src/tag/v1.1_000/firefox/00-proxy.yml>`
|
||||
|
||||
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 <glossary.html#term-mandatory-option>`
|
||||
according to the :xref:`Tiramisu <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 <glossary.html#term-mandatory-option>`
|
||||
according to the :xref:`Tiramisu <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 <src/tag/v1.1_002/firefox/00-proxy.yml>`
|
||||
|
||||
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
|
||||
|
||||
..
|
||||
|
||||
..
|
||||
<pre>╭──────────────────── Caption ─────────────────────╮
|
||||
│ <span style="color: #ff0000">Undocumented but modified variable</span> <span style="color: #ffd700">Default value</span> │
|
||||
╰──────────────────────────────────────────────────╯
|
||||
|
|
@ -192,11 +193,11 @@ we have this output:
|
|||
<span style="color: #5c5cff">┗━━ </span>📓 <span style="color: #ff0000">Configure Proxy Access to the Internet</span>: <span style="color: #ffd700">null</span>
|
||||
</pre>
|
||||
|
||||
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
|
||||
|
||||
..
|
||||
..
|
||||
<pre>╭─────── Caption ────────╮
|
||||
│ Variable <span style="color: #ffd700">Default value</span> │
|
||||
╰────────────────────────╯
|
||||
|
|
@ -244,19 +245,16 @@ The `proxy_mode` variable requires a value, that's why we have set a `No proxy`
|
|||
<span style="color: #5c5cff">┗━━ </span>📓 Configure Proxy Access to the Internet: <span style="color: #ffd700">No proxy</span>
|
||||
</pre>
|
||||
|
||||
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 <short-hand notation>` with Rougail that you may encounter
|
||||
There are some other :term:`short-hand ways <short-hand notation>` 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 <structure file>`\ .
|
||||
So far we have only talked about the actor that writes the :term:`structure files <structure file>`\ .
|
||||
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 <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 <user data file>`.
|
||||
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 <user data file>`.
|
||||
|
||||
.. 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 <structured data>`\ '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 <user data fi
|
|||
└── config
|
||||
└── config.yml
|
||||
|
||||
.. type-along:: how to set a user data value
|
||||
.. type-along:: How to set a user data value
|
||||
|
||||
If the integrator has not set any default value in his structure file,
|
||||
If the integrator has not set any default value in his structure file,
|
||||
it's up to the operator to do the job in the `config.yml` file:
|
||||
|
||||
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_003/config/02/config.yml
|
||||
:language: yaml
|
||||
:caption: A Rougail user datas file :file:`config/config.yml`, with a value set.
|
||||
:caption: A Rougail user data file :file:`config/config.yml`, with a value set.
|
||||
:name: RougailConfigDefaultValue
|
||||
|
||||
..
|
||||
..
|
||||
---
|
||||
proxy_mode: No proxy
|
||||
|
||||
:tutorial:`Download this file from the rougail-tutorials git repository <src/tag/v1.1_003/config/02/config.yml>`
|
||||
|
||||
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
|
||||
|
||||
..
|
||||
..
|
||||
<pre>╭──────── Caption ────────╮
|
||||
│ Variable Modified value │
|
||||
╰─────────────────────────╯
|
||||
|
|
@ -368,24 +366,24 @@ which gives us this output:
|
|||
<span style="color: #5c5cff">┗━━ </span>📓 proxy_mode: No proxy ◀ loaded from the YAML file "config/02/config.yml"
|
||||
</pre>
|
||||
|
||||
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`
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue