diff --git a/docs/cli.rst b/docs/cli.rst index 10fe98e5e..b4b2532d1 100644 --- a/docs/cli.rst +++ b/docs/cli.rst @@ -1,5 +1,17 @@ :orphan: +The Rougail Command Line Interface +======================================== + +Standard usage +----------------- + +:: + + rougail -m firefox/ -u yaml -yf config/02/config.yml + + + :: rougail --cli.versions @@ -25,5 +37,16 @@ "port": "8888" } +Invalid user data error +----------------------------- +:: + rougail -m firefox/ -u yaml -yf config/02/config.yml --cli.invalid_user_data_error + +Unknown user data error +----------------------------- + +l'option "`--cli.unknown_user_data_error`", ca ressemble à "`--cli.invalid_user_data_error`" mais ca concerne là les variables inconnues (ou ici désactivé ou hidden mais ca reviens au meme pour moi) chargés dans des user data. + +https://forge.cloud.silique.fr/stove/rougail-tutorials/src/commit/v1.1_050/README.md#output-when-unknown-user-data-is-an-error diff --git a/docs/tutorial/disabled.rst b/docs/tutorial/disabled.rst index d0598415e..d47f27ee9 100644 --- a/docs/tutorial/disabled.rst +++ b/docs/tutorial/disabled.rst @@ -5,13 +5,16 @@ Define access to variable or family In this section we will see what a disabled variable or family is, and why it can be interesting to assign the `disabled` property to a variable or a family. We'll also learn the difference - between disabling and hiding families or variables. + between disabling and hiding families or variables. + Then we'll see the same thing for the `hidden` property. We will: - create a `disabled` family - use a new family or variable's property: the `hidden` property +Disabling and hiding are two families or variables properties. + .. prerequisites:: Prerequisites - We assume that Rougail's library is :ref:`installed ` on your computer. @@ -30,11 +33,9 @@ Define access to variable or family git clone https://forge.cloud.silique.fr/stove/rougail-tutorials.git git switch --detach v1.1_050 -A disabled family ------------------- +.. type-along:: What a property is -Disabling and hiding are two families or variables properties. Let's begin with -defining what a property is: +Let's begin with defining what a property is: .. glossary:: @@ -122,6 +123,16 @@ It outputs: We can see that the Rougail CLI is warning us about the variables that we are trying to assign values on which are disabled. Because it is not logical. We are trying to assign values to variables that are not taken into account in the :term:`configuration`. +The point is that we disable them in order to expose the fact that we don't use them, +but it's not just that: if we fill them in, there might be a problem in the overall integrity of the whole :term:`configuration`. +We shall fill and use in these variables in the `Manual proxy configuration` use case context only. +Otherwise, **we need to disable them when they are not used**. + +In a practical point of view, if we fill them in, Rougail CLI will output a warning and the :term:`operator` will see it. +He will wonder : "oh, what am I doing?", I shall fill and use in these variables only in the `Manual proxy configuration` context. + +.. type-along:: The `disabling` property is usefull in our use case + Let's look again at our use case. We have a choice between five options in order to set the proxy mode: @@ -139,18 +150,11 @@ Actually if the `Manual proxy configuration` is not selected, we don't need to s these `address` and `port` variables, there is no point in setting them in four out of our five use cases. -The first point is that we disable them in order to expose the fact that we don't use them, -but it's not just that: if we fill them in, there might be a problem in the overall integrity of the whole :term:`configuration`. -We shall fill and use in these variables in the `Manual proxy configuration` use case context only. -Otherwise, **we need to disable them when they are not used**. - -In a practical point of view, if we fill them in, Rougail CLI will output a warning and the :term:`operator` will see it. -He will wonder : "oh, what am I doing?", I shall fill and use in these variables only in the `Manual proxy configuration` context. - .. important:: We need to **disable** variables or families that are not used in a given usage context. -.. type-along:: Disabling a family +A disabled family +------------------ Disabling variables one by one can be replaced by disabling a whole family. If we don't choose the manual mode, we need to **disable** the whole `manual` family, it will disable @@ -240,6 +244,14 @@ We can see here that the `manual` family disabled or enabled property is contiti The target variable is `_.proxy_mode`. .. note:: The `_.` notation means the current path of the family you're currently in. + + In the python quasi algorithmic notation we could say that: + + .. code-block:: python + + _.proxy_mode == proxy_mode + + This is true only because in our use case `proxy_mode` is located on the root path. Now regarding the `when_not` parameter, this means that if the target variable's value is `Manual proxy configuration` then the `manual` familiy **will not** be disabled @@ -360,7 +372,7 @@ Let's introduce a new property here: This is the main difference between the `hidden` and the `disabled` properties: - with the `disabled` property, the variables are *deactivated* - - with the `hidden` property, the variables are just not seen. + - with the `hidden` property, the variables are just not seen when loading the user data. Now we can set a `hidden` property to the `https_proxy` family: