proofreading
This commit is contained in:
gwen
parent
c2e8e3fd5a
commit
a3d7258a64
3 changed files with 92 additions and 73 deletions
|
|
@ -6,49 +6,33 @@ Getting started
|
|||
Installation
|
||||
----------------
|
||||
|
||||
You can use the python installer and type the install command in your preferred terminal:
|
||||
- Open a shell session
|
||||
|
||||
.. type-along:: Optional: install the Rougail library in a virtual environment
|
||||
|
||||
- install the virtual environment: `python -m"venv' .venv`
|
||||
- activate it `./.venv/bin/activate` (or `.venv\Scripts\activate.exe` under windows)
|
||||
|
||||
.. type-along:: Rougail's library installation
|
||||
|
||||
You can use the `pip` python installer, here is the install command:
|
||||
|
||||
.. code-block:: text
|
||||
|
||||
pip install rougail
|
||||
|
||||
Another way to install the Rougail library in install it in a virtual environment:
|
||||
|
||||
.. code-block:: text
|
||||
|
||||
python -m"venv' .venv
|
||||
|
||||
And, under linux or Mac:
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
./.venv/bin/activate
|
||||
|
||||
or, under windows:
|
||||
|
||||
.. code-block:: text
|
||||
|
||||
.venv\Scripts\activate.exe
|
||||
|
||||
Then again:
|
||||
|
||||
.. code-block:: text
|
||||
|
||||
pip install rougail
|
||||
|
||||
|
||||
What is a consistency handling system ?
|
||||
------------------------------------------------
|
||||
|
||||
.. questions:: Rougail, Tiramisu: What is all this stuff?
|
||||
.. questions:: Rougail, Tiramisu: What is it all about?
|
||||
|
||||
**Question**: OK, I have understood that the Rougail library enables me to take advantage of the :xref:`tiramisu` library. But what is all this for? What is exactly a consistency handling system? And again, what is this :xref:`tiramisu library` used for?
|
||||
**Question**: OK, I have understood that the Rougail library allows me to take advantage of the :xref:`tiramisu` consistency handling library. But what is all this for? What is exactly a consistency handling system? And again, what is this :xref:`Tiramisu library <tiramisu library>` used for?
|
||||
|
||||
**Answer**: Well, we will explain in details what this :xref:`tiramisu` library is and what Rougail is.
|
||||
|
||||
In (very) short:
|
||||
|
||||
- Rougail is the YAML consistency description of a configuration's situation
|
||||
- Rougail is the YAML consistency description of a :term:`context`\ 's situation
|
||||
- Tiramisu is the consistency engine linter
|
||||
|
||||
.. glossary::
|
||||
|
|
@ -56,7 +40,7 @@ What is a consistency handling system ?
|
|||
Tiramisu
|
||||
|
||||
:xref:`tiramisu` is a consistency handling system that has initially been designed
|
||||
in the configuration management scope. To put it more simply,
|
||||
in the configuration management scope. Until now,
|
||||
this library is generally used to handle configuration options.
|
||||
|
||||
It manages variables and group of variables. In the Tiramisu scope we call
|
||||
|
|
@ -64,7 +48,7 @@ What is a consistency handling system ?
|
|||
|
||||
Here is the :xref:`tiramisu documentation <tiramisu>`.
|
||||
|
||||
In the Rougail scope, we call it :term:`variable`\ s and :term:`families`.
|
||||
In the Rougail scope, we call it :term:`variables <variable>` and :term:`families <family>`.
|
||||
In Rougail, the families and variables are located in the :term:`structure files <structure file>`.
|
||||
|
||||
The structure files
|
||||
|
|
@ -75,15 +59,32 @@ The structure files
|
|||
structure file
|
||||
|
||||
A structure file in the Rougail meaning is a YAML file that describes variables
|
||||
and their dependencies / consistencies.
|
||||
and their dependencies.
|
||||
There can be a lot of structure files located in many different folders.
|
||||
|
||||
Rougail reads all the dictionaries and loads them into a single object
|
||||
that handles the variables consistency.
|
||||
Rougail reads all the structure files and loads them into a single object
|
||||
that represents the whole :term:`context`.
|
||||
|
||||
.. image:: images/schema.png
|
||||
.. figure:: images/schema.png
|
||||
:alt: The Rougail process
|
||||
:align: center
|
||||
|
||||
The main advantage is that declaring variables and writing consistency is as simple
|
||||
The Rougail process from structure files to Tiramisu object
|
||||
|
||||
.. glossary::
|
||||
|
||||
structured data
|
||||
|
||||
We sometimes call 'structured datas' the datas that are in the structure files,
|
||||
as opposed to :term:`user datas <user data>`\ .
|
||||
For example when a value of a variable is defined in the structured datas, that is
|
||||
in a structured file, the assigned value's status is that the variable's value is a default value.
|
||||
If the assigned value of the variable is defined in a user data file,
|
||||
it is an user assigned value.
|
||||
|
||||
We'll see later on some examples of default values and user assigned values.
|
||||
|
||||
The main advantage of all of this that declaring variables and writing consistency is as simple
|
||||
as writing YAML. With Rougail it is not necessary to write :term:`Tiramisu` code any more.
|
||||
It simplifies a lot of things.
|
||||
|
||||
|
|
|
|||
|
|
@ -1,10 +1,12 @@
|
|||
Tutorial with a real world sample
|
||||
=====================================
|
||||
|
||||
Here is a fairly complete tutorial, this is a use case that comes from the real world.
|
||||
Here is a fairly complete tutorial, it is a use case that comes from the real world.
|
||||
At the end of the tutorial you will have a good understanding of rougail.
|
||||
|
||||
.. objectives:: Configuring (the setting of) your favorite web browser
|
||||
.. objectives:: Objectives
|
||||
|
||||
Configuring (the setting of) your favorite web browser.
|
||||
|
||||
This tutorial will show you an example of Rougail use based on the
|
||||
*how to set a proxy* in the `Mozilla Firefox <https://www.mozilla.org/en-US/firefox/new/>`_ browser
|
||||
|
|
@ -14,22 +16,23 @@ More precisely, this tutorial aims at reproducing :term:`variable`\ s behind thi
|
|||
|
||||
.. image:: images/firefox.png
|
||||
|
||||
We'll call the variables **configuration options** since that's what the variables represent in this case.
|
||||
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
|
||||
with Rougail.
|
||||
|
||||
Let's dive into this **configuration options validation** use case.
|
||||
|
||||
Presentation of the firefox option configuration variables
|
||||
-----------------------------------------------------------
|
||||
|
||||
Let's dive into this **configuration options validation** use case.
|
||||
The values entered by the user have to be
|
||||
|
||||
- validated
|
||||
- consitent
|
||||
|
||||
At first glance we can see that we have a selection of five configuration options values that we need to fill in (they are highlighted here in this screenshot):
|
||||
At first glance we can see that we have a selection of five configuration options values that we need to fill in, they are highlighted here in this screenshot:
|
||||
|
||||
.. image:: images/firefox_01.png
|
||||
|
||||
|
|
|
|||
|
|
@ -11,11 +11,10 @@ Preliminaries
|
|||
|
||||
.. prerequisites:: Prerequisites
|
||||
|
||||
We assume that Rougail's library is :ref:`globally installed <installation>` on your computer or locally in a virtual environment.
|
||||
We assume that Rougail's library is :ref:`installed <installation>` on your computer.
|
||||
|
||||
.. type-along:: an empty structure file
|
||||
|
||||
An empty structure description file
|
||||
Making a structure file
|
||||
-------------------------
|
||||
|
||||
.. exercise:: The folder structure
|
||||
|
||||
|
|
@ -29,10 +28,9 @@ Preliminaries
|
|||
- First, we wil make a :term:`structure file <structure file>`, so let's create a :file:`struct.yml` file
|
||||
located in the :file:`firefox` subfolder.
|
||||
|
||||
The structure file
|
||||
--------------------
|
||||
.. type-along:: An empty structure file
|
||||
|
||||
This is an empty Rougail dictionnary
|
||||
This is an empty Rougail structure description file.
|
||||
|
||||
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_000/firefox/00-proxy.yml
|
||||
:language: yaml
|
||||
|
|
@ -43,14 +41,15 @@ This is an empty Rougail dictionnary
|
|||
---
|
||||
version: 1.1
|
||||
|
||||
.. type-along:: a first variable
|
||||
|
||||
Let's put a variable in the Rougail :term:`structure description file <structure file>`
|
||||
|
||||
Defining a variable and its default value
|
||||
----------------------------------------------
|
||||
|
||||
This is a first Rougail variable in a Rougail dictionnary.
|
||||
.. type-along:: a first variable
|
||||
|
||||
Let's put a variable in the Rougail :term:`structure description file <structure file>`
|
||||
|
||||
This is a first Rougail variable in a Rougail dictionnary:
|
||||
|
||||
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_010/firefox/00-proxy.yml
|
||||
:language: yaml
|
||||
|
|
@ -61,7 +60,7 @@ This is a first Rougail variable in a Rougail dictionnary.
|
|||
---
|
||||
proxy_mode:
|
||||
|
||||
- Then if we run the Rougail CLI utility command
|
||||
- If we run the Rougail CLI utility command
|
||||
|
||||
.. code-block:: text
|
||||
:class: terminal
|
||||
|
|
@ -81,10 +80,10 @@ we will actually have an error:
|
|||
|
||||
Because this variable is :term:`mandatory` and needs to be set **but** there's no value yet.
|
||||
|
||||
So we can therefore see this consequence:
|
||||
|
||||
.. important:: Once defined, an option configuration :term:`value` is :term:`mandatory`.
|
||||
We can therefore deduce this result:
|
||||
|
||||
.. note:: Once defined, an option configuration :term:`value` is :term:`mandatory`.
|
||||
|
||||
Rougail waits for the `proxy_mode` configuration option's value to be set.
|
||||
|
||||
.. seealso:: To go further, have a look at the :tiramisu:`mandatory option <glossary.html#term-mandatory-option>` according to the definition of Tiramisu.
|
||||
|
|
@ -93,10 +92,10 @@ Rougail waits for the `proxy_mode` configuration option's value to be set.
|
|||
|
||||
mandatory
|
||||
|
||||
A variable is mandatory when a value is required, that is, `None` is not an option.
|
||||
A variable is mandatory when a value is required, that is, `None` is not a possible value.
|
||||
It **must** have a defined value.
|
||||
|
||||
Then we just add a variable's description, which is a good practice.
|
||||
Let's add a variable's description, which is not mandatory but which is a good practice:
|
||||
|
||||
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_011/firefox/00-proxy.yml
|
||||
:language: yaml
|
||||
|
|
@ -108,7 +107,9 @@ Then we just add a variable's description, which is a good practice.
|
|||
proxy_mode:
|
||||
description: Configure Proxy Access to the Internet
|
||||
|
||||
We need a **default value**.
|
||||
.. type-along:: how to set a value -- the default value
|
||||
|
||||
We need to set a value to this `proxy_mode` variable. A first way to do it is *to set a value by default*.
|
||||
|
||||
.. glossary::
|
||||
|
||||
|
|
@ -131,20 +132,20 @@ So let's define a variable with a description -- **and a default value**
|
|||
default: No proxy
|
||||
|
||||
|
||||
.. type-along:: how to set a value
|
||||
.. type-along:: how to set a value -- the assignment
|
||||
|
||||
A default value has been set, great. Now how do I assign a value to a variable?
|
||||
|
||||
How to set a value
|
||||
----------------------
|
||||
|
||||
So far we have only talked about the one that writes the structure files. It's role is called the integrator's role.
|
||||
So far we have only talked about the one that writes the :term:`structure files <structure file>`\ . It's *role* is called the integrator's role.
|
||||
|
||||
.. glossary::
|
||||
|
||||
integrator
|
||||
|
||||
An integrator in the Rougail logic is the person who writes the :term:`structure files <structure file>`\ .
|
||||
An integrator in the Rougail field is the person who writes the :term:`structure files <structure file>`\ .
|
||||
He has the responsibilité of the integration process, that is,
|
||||
defines the variables and the relationship between them, the variables that are allowed
|
||||
(or not) to be set, and so on. His responsabilites are the **structuration** and the **consistency**
|
||||
|
|
@ -156,25 +157,29 @@ Now we will talk about the one that defines the values. It is called the operato
|
|||
|
||||
operator
|
||||
|
||||
An operator ih the Rougail logic is the person who gives :term:`value`\ s to the pre-defined variables,
|
||||
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 type validation is driven by the :term:`definitions in the structure file <structure file>`.
|
||||
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>`.
|
||||
|
||||
Values are mandatory
|
||||
-------------------------
|
||||
|
||||
It is the operator's responsibility to set the user datas variables values.
|
||||
The operator does not toutch the structure files,
|
||||
he is responsible for other files called the :term:`user data file`\ s.
|
||||
The operator does not handle the structure files,
|
||||
he is responsible of other files called the :term:`user data file`\ s.
|
||||
|
||||
.. glossary::
|
||||
|
||||
user datas
|
||||
|
||||
User datas, as opposed to structured datas, means datas where the consistency of the variables is not concerned, not in the scope (the consistency in the structured datas scope's).
|
||||
For example, variable's values (which are also called **user values**).
|
||||
|
||||
User datas, as opposed to structured datas, are datas that only concern the assignment of values
|
||||
and not the consistency of the variables.
|
||||
|
||||
The variable's values are also called **user values**.
|
||||
|
||||
The consistency field is outside of the user datas scope.
|
||||
The consistency is handled in the :term:`structured datas <structured data>`\ 's scope.
|
||||
|
||||
.. exercise:: Folder structure update
|
||||
|
||||
|
|
@ -218,8 +223,12 @@ Let us clarify this essential point:
|
|||
Variable's type
|
||||
-----------------
|
||||
|
||||
.. type-along:: type inference
|
||||
|
||||
If the `type` attribute is not set, Rougail infers a `string` type for the `proxy_mode` configuration option variable type as defined in the structure file.
|
||||
|
||||
.. type-along:: type setting
|
||||
|
||||
If the operator sets an option value for example with the `number` type, like this:
|
||||
|
||||
.. code-block:: yaml
|
||||
|
|
@ -230,11 +239,17 @@ If the operator sets an option value for example with the `number` type, like th
|
|||
type: number
|
||||
|
||||
Then Rougail will expect a `int` or a `float` as a value for the `example_var` variable.
|
||||
In our firefox use case, the real type of the `proxy_mode` variable will be now set as a `choice` type:
|
||||
|
||||
.. type-along:: Defining a choice type
|
||||
|
||||
A choice type variable is a variable where the content is constrained by a list
|
||||
In our firefox use case, the real type of the `proxy_mode` variable will be now set as a `choice` type:
|
||||
|
||||
|
||||
.. glossary::
|
||||
|
||||
choice type
|
||||
|
||||
A choice type variable is a variable where the content is constrained by a list
|
||||
|
||||
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_013/firefox/00-proxy.yml
|
||||
:linenos:
|
||||
|
|
@ -255,14 +270,14 @@ In our firefox use case, the real type of the `proxy_mode` variable will be now
|
|||
- Automatic proxy configuration URL
|
||||
default: No proxy
|
||||
|
||||
- Then if we run the Rougail CLI
|
||||
- Let's run the Rougail CLI
|
||||
|
||||
.. code-block:: text
|
||||
:class: terminal
|
||||
|
||||
rougail -v 1.1 -m firefox/
|
||||
|
||||
We will have an output like this:
|
||||
We have an output like this one:
|
||||
|
||||
.. raw:: html
|
||||
:url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_013/config/01/output_ro.html
|
||||
|
|
|
|||
Loading…
Reference in a new issue