diff --git a/docs/gettingstarted.rst b/docs/gettingstarted.rst index 19f274370..f356ef606 100644 --- a/docs/gettingstarted.rst +++ b/docs/gettingstarted.rst @@ -30,15 +30,16 @@ What is a consistency handling system ? Here is the :xref:`tiramisu library`. In the Rougail scope, we call it :term:`variable`\ s and :term:`families`. -In Rougail, the families and variables are located in the :term:`dictionaries`. +In Rougail, the families and variables are located in the :term:`structure files `. And this is what we are going to explain in this page. -The dictionaries +The structure files --------------------- .. glossary:: + structure file dictionary dictionaries @@ -49,6 +50,8 @@ The dictionaries Rougail reads all the dictionaries and loads them into a single object that handles the variables consistency. + A dictionary file is a structure file, we call a dictionary a structure file. + .. image:: images/schema.png The main advantage is that declaring variables and writing consistency is as simple @@ -57,10 +60,10 @@ It simplifies a lot of things. And rather than writing :term:`Tiramisu` code, we can declare variables and describe the relationships between variables in a declarative mode (that is, in a YAML file). -Once the dictionaries are loaded by Rougail, we find all the power of the :term:`Tiramisu` configuration management tool. +Once the structure files are loaded by Rougail, we find all the power of the :term:`Tiramisu` configuration management tool. -The YAML dictionaries format ------------------------------ +The YAML structure files format +------------------------------------ Before getting started with Rougail we need to learn the specifics of the YAML dictionaries file format (as well as some templating concepts). @@ -95,7 +98,7 @@ You can see that there is just a `version` specification. The variables ----------------- -Here is a :term:`dictionary` example with a variable into it: +Here is a :term:`structure file ` example with a variable into it: .. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_003/firefox/00-proxy.yml :linenos: @@ -105,7 +108,7 @@ Here is a :term:`dictionary` example with a variable into it: :download:`source file ` -Here we declare a **variable** named `proxy_mode` without a :term:`default value`. +Here we declare a **variable** named `proxy_mode` without a default value. A variable can be defined with no default value at all. Here is the same variable with a description label: diff --git a/docs/tutorial/preliminary.rst b/docs/tutorial/preliminary.rst index 21cf8cc2c..fb7603768 100644 --- a/docs/tutorial/preliminary.rst +++ b/docs/tutorial/preliminary.rst @@ -5,7 +5,7 @@ Preliminaries We will learn how to: - - create a Rougail :term:`dictionary` (the structure description file) + - create a Rougail :term:`structure description file ` - define a Rougail format version - define a Rougail :term:`variable` and set its :term:`value` @@ -13,7 +13,7 @@ Preliminaries We already learned in other workshops how to: - - define a Rougail :term:`dictionary` + - define a Rougail :term:`structure description file ` :ref:`Here is an empty Rougail dictionnary ` @@ -29,41 +29,6 @@ Preliminaries :ref:`Here is a Rougail variable with a default value ` -Values are mandatory -------------------------- - -If, like in this situation: - -.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_004/firefox/00-proxy.yml - :linenos: - :language: yaml - :caption: The :file:`config/01/config.yaml` rougail dictionnary file, with no default value set. - :name: RougailDictionaryNoDefaultUseCase - -In this situation there are no default value set. The rougail CLI will output an error : - -.. code-block:: shell - :caption: A rougail Command Line Utility call with the :file:`config/01/config.yaml` rougail dictionnary file - - foo@bar:~$ rougail -v 1.1 -m firefox -u file -ff config/01/config.yaml - - -.. raw:: html - - 
-
-.. raw:: html
-   :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_003/config/01/output_ro.html
-
-.. raw:: html
-
-
- -Rougail waits for a value to be set, that's why. - - -.. seealso:: To go further, have a look at the :tiramisu:`mandatory option ` Tiramisu's definition. - The integrator role ---------------------- @@ -72,7 +37,7 @@ The integrator role integrator - An integrator in the Rougail logic is the person who writes the dictionaries. + An integrator in the Rougail logic is the person who writes the :term:`structure files `\ . 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** @@ -94,7 +59,7 @@ The operator role 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 validated - by the dictionary structure. + by the :term:`structure file `. .. image:: images/operator.png @@ -108,11 +73,57 @@ The Rougail CLI can output a rather complete view of the dataset: .. image:: images/UserDataOutput.png +Values are mandatory +------------------------- + +It is the operator's responsibility to set configuration options values. + +So, if : + +- there is no default value set in the structure file, +- no value is set in the value file: + +.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_004/firefox/00-proxy.yml + :linenos: + :language: yaml + :caption: The :file:`config/01/config.yaml` rougail dictionnary file, with no default value set. + :name: RougailDictionaryNoDefaultUseCase + +In this situation there are no default value set. The rougail CLI will output an error : + +.. code-block:: shell + :caption: A rougail Command Line Utility call with the :file:`config/01/config.yaml` rougail dictionnary file + + foo@bar:~$ rougail -v 1.1 -m firefox -u file -ff config/01/config.yaml + +.. raw:: html + :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_003/config/01/output_ro.html + + +Rougail waits for a value to be set, that's why. + +.. seealso:: To go further, have a look at the :tiramisu:`mandatory option ` Tiramisu's definition. + +Type inférence +----------------- + +By default, rougail infers a `string` type. +If the operator sets an option value with the `string` type, like this: + +.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_003/config/05/config.yaml + :linenos: + :language: yaml + :caption: The :file:`config/05/config.yaml` rougail dictionnary file, with no default value set. + :name: RougailDictionaryNoDefaultUseCaseIntOptionValue + +.. raw:: html + :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_003/config/05/output_ro.html + .. keypoints:: Key points progress **Keywords** - - :term:`dictionary`: structure description file + - :term:`structure file `: structure description file - :term:`variable`: an option's name which has a value - a variable's description - a variable's default value