diff --git a/docs/tutorial/choice.rst b/docs/tutorial/choice.rst index 85b29b304..9239f927f 100644 --- a/docs/tutorial/choice.rst +++ b/docs/tutorial/choice.rst @@ -9,12 +9,12 @@ A variable with possible values - We assume that Rougail's library is :ref:`installed ` on your computer. - - It is possible to retrieve the current state of the various rougail files manipulated in this tutorial step - by checking out the corresponding tag of the Rougail-tutorials git repository. + - It is possible to retrieve the current state of the various Rougail files manipulated in this tutorial step + by checking out the corresponding tag of the `rougail-tutorials` git repository. 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 tag :tutorial:`v1.1_010 ` in the repository: :: @@ -30,7 +30,7 @@ In the firefox browser, the proxy mode can be set by this way: .. image:: images/firefox_02.png A list of possible values for the `proxy_mode` variable ​​is proposed. -With rougail there is the possibility of defining a list of available values +With Rougail there is the possibility of defining a list of available values with the `choice` variable's parameter: .. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_010/firefox/00-proxy.yml @@ -89,7 +89,7 @@ by the possibilities of the `choice` parameter. :tutorial:`Download this file from the rougail-tutorials git repository ` -If we run the rougail CLI with this user datas: +If we run the Rougail CLI with this user datas: .. raw:: html :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_010/config/03/cmd_ro.txt @@ -115,7 +115,7 @@ We have this output: As we set the `proxy_mode` variable from a user data file, we now have specified a value which is **not** a default value, and -the output of the rougail CLI explicitly shows that a user data value has been entered, +the output of the Rougail CLI explicitly shows that a user data value has been entered, it shows which user data file this value comes from, and it also indicates what the default value is for information purposes. @@ -142,7 +142,7 @@ We have the list of the possible (authorized) values: :tutorial:`Download this file from the rougail-tutorials git repository ` -If we run the rougail CLI with this user datas: +If we run the Rougail CLI with this user datas: .. raw:: html :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_010/config/04/cmd_ro.txt @@ -160,12 +160,12 @@ We have this output: We can see here that Rougail warns us about an invalid value that is not in the available choices, that's why this value will not be used and it falls back to the original default value. -But maybe this is not the behavior you need. Maybe you need to stop everything if rougail detects that +But maybe this is not the behavior you need. Maybe you need to stop everything if Rougail detects that something is going wrong, maybe you need some kind of a strict mode. Indeed, this warning can be transformed into an error. -If we run the rougail CLI with this `--cli.invalid_user_datas_error` parameter: +If we run the Rougail CLI with this `--cli.invalid_user_datas_error` parameter: .. raw:: html :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_010/config/04/cmd_invalid.txt diff --git a/docs/tutorial/domainname.rst b/docs/tutorial/domainname.rst index e4794d289..4869eeaff 100644 --- a/docs/tutorial/domainname.rst +++ b/docs/tutorial/domainname.rst @@ -10,12 +10,12 @@ Some suitable types - We assume that Rougail's library is :ref:`installed ` on your computer. - - It is possible to retrieve the current state of the various rougail files manipulated in this tutorial step - by checking out the corresponding tag of the Rougail-tutorials git repository. + - It is possible to retrieve the current state of the various Rougail files manipulated in this tutorial step + by checking out the corresponding tag of the `rougail-tutorials` git repository. 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_030 ` to :tutorial:`v1.1_033 ` in the repository. @@ -69,7 +69,7 @@ Well, with a correct user data like this one, :tutorial:`Download this file from the rougail-tutorials git repository ` -if we launch the rougail CLI on it: +if we launch the Rougail CLI on it: .. raw:: html :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_030/config/01/cmd_ro.txt @@ -117,7 +117,7 @@ Let's have a look at an example of user setting that does not fit the :tutorial:`Download this file from the rougail-tutorials git repository ` -The value is obviously not a domain name, then when we will launch the rougail CLI: +The value is obviously not a domain name, then when we will launch the Rougail CLI: .. raw:: html :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_030/config/03/cmd_invalid.txt @@ -153,7 +153,7 @@ we then have this output: :tutorial:`Download this file from the rougail-tutorials git repository ` -With a value that *is not a domain name* but an IP address, then when we will launch the rougail CLI +With a value that *is not a domain name* but an IP address, then when we will launch the Rougail CLI we will see a little problem: .. raw:: html @@ -245,7 +245,7 @@ Now we will test with an IP address as the value for our `address` variable. :tutorial:`Download this file from the rougail-tutorials git repository ` -if we launch the rougail CLI on it: +if we launch the Rougail CLI on it: .. raw:: html :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_031/config/02/cmd_ro.txt @@ -305,7 +305,7 @@ Let's assing a value to this port: :tutorial:`Download this file from the rougail-tutorials git repository ` -If we launch the rougail CLI: +If we launch the Rougail CLI: .. raw:: html :class: terminal @@ -350,7 +350,7 @@ Now let's assign a value that is outside the allowed ports: :tutorial:`Download this file from the rougail-tutorials git repository ` -Again, we launch the rougail CLI: +Again, we launch the Rougail CLI: .. raw:: html :class: terminal @@ -425,7 +425,7 @@ Let's switch this boolean variable to a `false` value: :tutorial:`Download this file from the rougail-tutorials git repository ` -Let's run the rougail CLI: +Let's run the Rougail CLI: .. raw:: html :class: terminal diff --git a/docs/tutorial/family.rst b/docs/tutorial/family.rst index b80ff5996..4178c387d 100644 --- a/docs/tutorial/family.rst +++ b/docs/tutorial/family.rst @@ -13,12 +13,12 @@ Group variables inside families - We assume that Rougail's library is :ref:`installed ` on your computer. - - It is possible to retrieve the current state of the various rougail files manipulated in this tutorial step - by checking out the corresponding tag of the Rougail-tutorials git repository. + - It is possible to retrieve the current state of the various Rougail files manipulated in this tutorial step + by checking out the corresponding tag of the `rougail-tutorials` git repository. 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_020 ` to :tutorial:`v1.1_022 ` in the repository. @@ -143,7 +143,6 @@ Putting a variable inside of a family or a sub family git switch --detach 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. @@ -247,7 +246,7 @@ 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 datas. 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` diff --git a/docs/tutorial/preliminary.rst b/docs/tutorial/preliminary.rst index d4629e0c7..fe8571196 100644 --- a/docs/tutorial/preliminary.rst +++ b/docs/tutorial/preliminary.rst @@ -13,12 +13,12 @@ Getting started - We assume that Rougail's library is :ref:`installed ` on your computer. - - It is possible to retrieve the current state of the various rougail files manipulated in this tutorial step - by checking out the corresponding tag of the Rougail-tutorials git repository. + - It is possible to retrieve the current state of the various Rougail files manipulated in this tutorial step + by checking out the corresponding tag of the `rougail-tutorials` git repository. 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: @@ -46,7 +46,7 @@ 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 + :caption: An empty Rougail structure file with only the YAML header and the version number :name: RougailStructVersion .. @@ -55,7 +55,7 @@ This is an empty Rougail :term:`structure description file: ` :tutorial:`Download this file from the rougail-tutorials git repository ` -This `version` specification is just the rougail YAML's format version specification. +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. Let's add our first variable @@ -127,7 +127,7 @@ Rougail expects the `proxy_mode` configuration option's value to be set. Describe the variable ------------------------- - + Let's add a variable's description, which is not mandatory but which is usually a good practice. .. type-along:: For those who follow the tutorial with the help of the git repository @@ -185,7 +185,7 @@ 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 - :caption: A rougail structure file with a default value for the variable + :caption: A Rougail structure file with a default value for the variable :name: RougailDictionaryVariableDefault .. @@ -209,44 +209,24 @@ The `proxy_mode` variable requires a value, that's why we have set a `No proxy` 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. +The chosen value is indicated in the Rougail's CLI output as the default choice. -.. glossary:: +- here is the short-hand default setting and description: - short-hand notation - - A short-hand notation in rougail is the ability to define a variable in - a short-hand way, there are several example: +.. code-block:: yaml - - a default value: - - .. code-block:: yaml - - my_var: true - - instead of: - - .. code-block:: yaml - - my_var: - default: true + proxy_mode: No proxy # Configure Proxy Access to the Internet - - a quick description: +- here is the verbose way: - .. code-block:: yaml - - proxy_mode: # Configure Proxy Access to the Internet - - instead of: +.. code-block:: yaml - - .. code-block:: yaml - - proxy_mode: - description: Configure Proxy Access to the Internet + proxy_mode: + default: No proxy + description: Configure Proxy Access to the Internet - There are some other short-hand ways with rougail that you may encounter - as you read the rougail's documentation and tutorial. +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 @@ -254,9 +234,9 @@ The chosen value is indicated in the rougail's CLI output as the default choice. Now then how can I assign a normal value to a variable? -.. type-along:: The different rougail roles and setting a variable's value +.. type-along:: The different Rougail roles and setting a variable's value -So far we have only talked about the guy 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,7 +277,8 @@ he is responsible of other files called the :term:`user data files `\ 's scope. -.. important:: If user datas are not set, default values are mandatory, otherwise Rougail will raise an error. +.. 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 @@ -325,7 +306,7 @@ it's up to the operator to do the job in the `config.yml` file: :tutorial:`Download this file from the rougail-tutorials git repository ` -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 @@ -348,13 +329,13 @@ 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 -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 diff --git a/docs/variable.rst b/docs/variable.rst index 73bea30df..ee087b37e 100644 --- a/docs/variable.rst +++ b/docs/variable.rst @@ -73,6 +73,26 @@ Shorthand declaration Shorthand declaration is a way to declare a variable in a single line. But you can only define variable name, description, multi or default value. +.. glossary:: + + short-hand notation + + A short-hand notation in Rougail is the ability to define a variable in + a short-hand way, there are several example: + + - a default value: + + .. code-block:: yaml + + my_var: true + + instead of: + + .. code-block:: yaml + + my_var: + default: true + To create a variable, just add a key with it's name and default value as value. Be careful not to declare any other attributes.