diff --git a/docs/conf.py b/docs/conf.py index b29e22903..bcf7e46af 100755 --- a/docs/conf.py +++ b/docs/conf.py @@ -14,7 +14,7 @@ todo_include_todos = True # -- Project information ----------------------------------------------------- project = 'Rougail' -copyright = '2019-2024, Silique' +copyright = '2019-2025, Silique' author = 'gwen' # The short X.Y version diff --git a/docs/tutorial/disabled.rst b/docs/tutorial/disabled.rst index e6e841512..d0f998f31 100644 --- a/docs/tutorial/disabled.rst +++ b/docs/tutorial/disabled.rst @@ -27,8 +27,8 @@ A family can disapear in the outerspace A disabled family ----------------------- -Let's come back to our use case, we have a choice to make between five options -to make a choice in order to set the proxy mode: +Let's come back to our use case, we have a choice between five options +in order to set the proxy mode: .. image:: images/firefox_01.png @@ -128,6 +128,74 @@ As expected, we encounter an error: ┗━━ 📓 proxy_mode: Manual proxy configuration (No proxy) +To avoid this type of error, What we need is a *dynamic setting* of the disable/enable property. + +.. type-along:: The conditional disabled property + + +A conditional disabled family +------------------------------ + + +If the manual mode for the proxy is not selected, then the `manual` family shall be disabled. +On the other hand, if the manual proxy's configuration mode is selected, +then we need to activate the `manual` family. + +And we understand that this activation/deactivation of the `manual` family +depends on the value of the `proxy_mode` variable. + +In rougail, we can set a property's value depending on the value of another variable. That is, it is conditioned by another variable. + +Here is how we can achieve this: + +.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_028/firefox/10-manual.yml + :linenos: + :language: yaml + :caption: The `manual` family in the :file:`firefox/10-manual.yml` structure file with a conditional disabled property + +.. + --- + manual: + description: Manual proxy configuration + disabled: + type: variable + variable: proxy_mode + when_not: 'Manual proxy configuration' + + http_proxy: + description: HTTP Proxy + + address: + description: HTTP address + type: domainname + params: + allow_ip: true + + port: + description: HTTP Port + type: port + default: 8080 + +.. rubric:: Explanation + +Here we have the `disabled` property like this: + +.. code-block:: yaml + + disabled: + type: variable + variable: proxy_mode + when_not: 'Manual proxy configuration' + +It means that the `disabled` property depends ont he `proxy_mode` variable: + +- if `proxy_mode == 'Manual proxy configuration'` disabled is false (that is, + the `manual` family is **enabled**) +- else the `disabled` property is true (that is, the `manual` family is **disabled**) + + + + .. keypoints:: Key points progress **Keywords** @@ -136,10 +204,11 @@ As expected, we encounter an error: - the `disabled` property - disabled variable or family - raising a configuration's consistency error - + - variable based conditional disabled family + **Progress** - we have a :term:`family` named `manual` and a sub family named `http_proxy` - And we have now two variables: :confval:`proxy_mode` and :confval:`address`. - - We have disabled the `http_proxy` sub family. + - We have disabled the `manual` family (and the `http_proxy` sub family).