diff --git a/docs/tutorial/family.rst b/docs/tutorial/family.rst index debe5723e..251b12e22 100644 --- a/docs/tutorial/family.rst +++ b/docs/tutorial/family.rst @@ -19,7 +19,7 @@ Group variables inside families 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 `, - this workshop page corresponds to the tags :tutorial:`v1.1_020 ` in the repository: + this workshop page corresponds to the tags :tutorial:`v1.1_020 ` in the repository: FIXME: END TAG :: @@ -58,10 +58,7 @@ In short, let's describe our `proxy_mode` variable like this: Proxy mode's settings Now we will define new variables, and other structure definitions. - - For the sake of clarity, we will put the structure definitions in separate files. - Please have a look at the :ref:`file naming and organizing convention `. Here we made a :file:`firefox/00-proxy.yml` structure file and we're gonna make @@ -89,7 +86,7 @@ Let's create a family named `manual` which obviously corresponds to the proxy's type: family We can see that we have defined a :term:`family` here, and this family is *empty* -(that is the family which is a container variable contains no variable yet). +which means that this family is a container variable that contains no variable yet. .. warning:: @@ -98,13 +95,26 @@ We can see that we have defined a :term:`family` here, and this family is *empty We have to force the family type inference. It's because we don't have set any :term:`variable` inside yet. When we will have a variable inside of this family, - we will make a YAML block (that is, we just indent the lines) and the Rougail's type inference engine will implicitely infer the variable's container as a family type. + we will make a YAML block (to create a block in YAML, you just need to indent the lines) and the Rougail's type inference engine will implicitely infer the variable's container as a family type. -.. type-along:: A family inside a family +Or a sub family +---------------- + +.. type-along:: For those who follow the tutorial with the help of the git repository + + Now you need to checkout the `v1.1_021` version:: + + git checkout v1.1_021 + +.. glossary:: + + sub family + + A sub family is a family inside a family. Creating a family hierarchy of family container types is very easy, here is an example: -.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_011/firefox/10-manual.yml +.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_021/firefox/10-manual.yml :language: yaml :caption: A rougail structure description file with a hierarchy. :name: RougailFirstFamilyHierarchy @@ -119,15 +129,26 @@ Creating a family hierarchy of family container types is very easy, here is an e description: HTTP Proxy type: family -Here the `http_proxy` family lives inside the `manual` family. +:tutorial:`Download this file from the rougail-tutorials git repository ` + +Note that the `http_proxy` family lives inside the `manual` family. Putting a variable inside of a family or a sub family ----------------------------------------------------------- +----------------------------------------------------------- + +.. type-along:: For those who follow the tutorial with the help of the git repository + + Now you need to checkout the `v1.1_022` version:: + + git checkout v1.1_022 + + +We are going to put a variable inside of a family or a sub family Let's create a variable in the `http_proxy` family. This time, the type of this new variable is a `domainname` type: -.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_012/firefox/10-manual.yml +.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_022/firefox/10-manual.yml :language: yaml :caption: An `address` variable in the `http_proxy` family :name: RougailVariableInSubFamily @@ -146,9 +167,11 @@ This time, the type of this new variable is a `domainname` type: description: HTTP address type: domainname -Now that the :confval:`address` variable is declarde, the :term:`operator` can set :term:`a value ` to the :confval:`address` variable +:tutorial:`Download this file from the rougail-tutorials git repository ` -So we have now an :confval:`address` variable: +Now that the :confval:`address` variable is declared, the :term:`operator` can set :term:`a value ` to it. + +In short, let's describe our `address` variable like this: .. confval:: address :type: `domainname` @@ -159,14 +182,17 @@ So we have now an :confval:`address` variable: .. note:: We encountered here a new type of variable there: the `domainname` type. There are a bunch of types available in Rougail. -Assigning a user value ------------------------------------- +We have reached the definition of the address in the `http_proxy` family; there will be other variables to define in this family. + +.. image:: images/firefox_manual_family.png + +.. type-along:: Assigning a user value Now we need to set a value ​​for the :confval:`address` variable, otherwise we will get an error if we try to access this variable: .. raw:: html - :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/src/tag/v1.1_012/config/01/output_ro.html + :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_022/config/01/output_ro.html :class: error-box .. @@ -175,30 +201,13 @@ otherwise we will get an error if we try to access this variable: ┗━━ - manual.http_proxy.address (HTTP address) -Because the :term:`mandatory` variable attribute is infered by default for this variable. - -.. type-along:: user data files are where the user values lives - -And we need to set the values ​​in separate files too, called `user data files`. - -.. glossary:: - - user data file - - A user data file is a file where only :term:`user datas` are set. - - A user file is a file where there are only user datas 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` - .. type-along:: let's set user values in a user data file Here is a user data file sample: -.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_012/config/03/config.yml +.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_022/config/03/config.yml :language: yaml - :caption: A user file named :file:`config/config.yaml` with a value set for the `address` variable + :caption: A user file named :file:`config/03/config.yml` with a value set for the `address` variable :name: RougailAddresseVariableUserValue .. @@ -208,14 +217,9 @@ Here is a user data file sample: http_proxy: address: example.net -.. glossary:: +Let's validate the consitency of the :term:`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. - -Let's validate the consitency of the configuration: +FIXME: RAW HTML HERE .. code-block:: text :class: terminal @@ -224,8 +228,10 @@ Let's validate the consitency of the configuration: Everything is OK: +FIXME : l'ouput ne sort pas (erreur 404) + .. raw:: html - :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_012/config/03/output_rw.html + :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_022/config/03/output_rw.html :class: output .. @@ -272,7 +278,7 @@ This is where the ability to parameterize our variable comes in. params: allow_ip: true -.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_024/firefox/10-manual.yml +.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_034/firefox/10-manual.yml :language: yaml :caption: The `address` has a parameter set in the :file:`firefox/10-manual.yml` structure file :name: RougailAddressParameter @@ -312,7 +318,7 @@ Let's create a `port` variable in the `http_proxy` family: Here is the new :file:`firefox/10-manual.yml` structure file: -.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_012/firefox/10-manual.yml +.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_022/firefox/10-manual.yml :language: yaml :caption: A rougail structure description file with a hierarchy. :name: RogailPortVariable diff --git a/docs/tutorial/images/firefox_manual_family.png b/docs/tutorial/images/firefox_manual_family.png new file mode 100644 index 000000000..049d267c2 Binary files /dev/null and b/docs/tutorial/images/firefox_manual_family.png differ diff --git a/docs/tutorial/preliminary.rst b/docs/tutorial/preliminary.rst index 8d30c027c..1b3c4b2c4 100644 --- a/docs/tutorial/preliminary.rst +++ b/docs/tutorial/preliminary.rst @@ -365,6 +365,28 @@ It can come from an integrator's setting or from an operator's setting. 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`. + +.. glossary:: + + user data file + + A user data file is a file where only :term:`user datas` are set. + + A user file is a file where there are only user datas 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` + +.. glossary:: + + 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. + .. keypoints:: Key points progress **Keywords** @@ -376,4 +398,5 @@ here we are talking about roles and not necessarily about people. - a variable's default value - a variable's user value - the :term:`integrator` and :term:`operator` roles + - a :term:`configuration`