stove/rougail
3
0
Fork 0
Code Issues 5 Pull requests 1 Projects Releases Wiki Activity

typos

Browse source
This commit is contained in:
gwen 2026-01-07 16:42:21 +01:00
parent eeba802047
commit 6da067f206
2 changed files with 11 additions and 393 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

22
docs/tutorial/disabled.rst
View file

@ -1,15 +1,17 @@
Disabling things
========================
Define access to variable or family
==========================================
.. objectives:: Objectives
FIXME: refaire les objectifs
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.
We will:
- `disable` a whole family here (yes, a family can disapear in the outerspace!)
- create a `disabled` family
- use a new family or variable's property: the `hidden` property
- reuse a value of a variable for another variable
(in this use case we will reuse the HTTP configuration variables values for the configuration of the HTTPS).
@ -123,7 +125,7 @@ It outputs:
:class: output
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 at the :term:`configuration` level.
Because it is not logical. We are trying to assign values to variables that are not taken into account in the :term:`configuration`.
Let's look again at our use case. We have a choice between five options
in order to set the proxy mode:
@ -242,8 +244,7 @@ will be used to dynamically enable or disable our `manual` family.
We can see here that the `manual` family disabled or enabled property is contitionned by the `_.proxy_mode` variable's value.
The target variable is `_.proxy_mode`.
The `.` notation means the path of the family or subfamily you're currently in.
The `_.` notation means the parent path of the current family or subfamily path.
.. note:: The `_.` notation means the current path of the family you're currently in.
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
@ -519,7 +520,7 @@ We have added two other variables for the HTTPS use only:
This is a port setting for the manual HTTPS configuration
We have now two very similar variables, a `manual.http_proxy.address` variable and a `manual.https_proxy.address` variable
We have now two very similar variables, a `manual.http_proxy.address` variable and a `manual.https_proxy.address` variable.
In the same way, we have a `manual.http_proxy.port` variable and a `manual.https_proxy.port` variable.
Let's introduce a new Rougail concept here:
@ -529,9 +530,9 @@ Let's introduce a new Rougail concept here:
context
A :term:`configuration` is highly statefull and can change at any moment.
Sometimes somes minor changes in the :term:`user datas <user data>` may involve chain reactions
Sometimes somes minor changes in the :term:`user data <user data>` may involve chain reactions
in the whole :term:`configuration`.
The **context** is the state of the user datas at one moment, the set of the values of the variables
The **context** is the state of the user data at one moment, the set of the values of the variables
at a given moment.
This term refers in Rougail to the ability of a system to handle
@ -698,8 +699,7 @@ here are the two :file:`firefox/10-manual.yml` and :file:`firefox/20-manual.yml`
We can see here that the `address` variable's default value is contitionned by the `__.http_proxy.address` variable's value.
The target variable is `http_proxy.address`.
The `.` notation means the path of the family or subfamily you're currently in.
The `__.` notation means the parent path of the parent path of the current subfamily path.
The `__.` notation means the parent path of the current subfamily path.
.. note:: We also say that the `manual.https_proxy.address` and the the `manual.https_proxy.port` default values are *calculated*.

382
docs/tutorial/hidden.rst
View file

@ -1,382 +0,0 @@
:orphan:
The `hidden` property
=======================
.. objectives:: Objectives
In this section we will:
- use a new family or variable's property: the `hidden` property
- create a variable with a new type, the `boolean` type
- reuse a value of a variable for another variable
(in this use case we will reuse the HTTP configuration variables values for the configuration of the HTTPS).
.. prerequisites:: Reminder
Let's summarize the configuration up to here
Whe have the `proxy_mode` configuration here:
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_030/firefox/00-proxy.yml
:language: yaml
:caption: firefox/00-proxy.yml
..
---
proxy_mode:
description: Configure Proxy Access to the Internet
choices:
- No proxy
- Auto-detect proxy settings for this network
- Use system proxy settings
- Manual proxy configuration
- Automatic proxy configuration URL
default: No proxy
With the `manual` family that is used in case of the `"Manual proxy configuration"` value of the `proxy_mode` variable has been chosen:
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_030/firefox/10-manual.yml
:language: yaml
:caption: firefox/10-manual.yml
..
---
manual:
description: Manual proxy configuration
disabled:
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
OK then. Let's continue our proxy's configuration.
.. type-along:: The HTTPS mode
Now we will focus on configuring the HTTPS mode in case of `"Manual proxy configuration"` value has been chosen.
.. image:: images/firefox_manual_https.png
We are going to define two other variables for the HTTPS use only:
.. confval:: https_proxy.address
:type: `domainname`
This is an address setting for the manual HTTPS configuration
.. confval:: https_proxy.port
:type: `port`
This is a port setting for the manual HTTPS configuration
- There are now two very similar variables, a `manual.http_proxy.address` variable and a `manual.https_proxy.address` variable
- In the same way, we have a `manual.http_proxy.port` variable and a `manual.https_proxy.port` variable.
The context
--------------
Let's introduce a new Rougail concept here:
.. glossary::
context
A :term:`configuration` is highly statefull and can change at any moment.
Sometimes somes minor changes in the :term:`user datas` may involve chain reactions
in the whole :term:`configuration`.
The **context** is the state of the user datas at one moment. The set of the values of the variables
at a given moment.
This term also refers
to the ability of a system to handle the *statefull* state of a configuration.
It expresses the transition between one situation to another situation,
that is, the deeply **statefull** aspects of a data set.
.. type-along:: A new variable which has the `boolean` type
The best way to reproduce the `"Also use this HTTP proxy variables for HTTPS"` checkbox in the firefox interface
is to add a boolean variable in our structure. A boolean variable can reproduce this binary choice option.
Do we want to reuse, for the HTTPS mode, the same configuration as for the HTTP mode?
Well, it depends on the :term:`context`.
Let's create a new variable, named `use_for_https` here:
.. confval:: use_for_https
:type: `boolean`
:default: `true`
This is a setting that enables to reuse or not the HTTP proxy configuration for HTTPS
.. questions:: Question: how does it work?
How will this variable drive the reuse of HTTP data to HTTPS data?
Its description in the structure file gives us this:
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_030/firefox/20-manual.yml
:language: yaml
:caption: firefox/20-manual.yml
..
---
manual:
use_for_https:
description: Also use this proxy for HTTPS
type: boolean
default: true
.. prerequisites:: Reminder
So now we have three new variables in the `manual` family (with its `https_proxy` subfamily) which express the manual mode of the http proxy configuration.
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_032/firefox/20-manual.yml
:language: yaml
:caption: `firefox/20-manual.yml`
..
---
manual:
use_for_https:
description: Also use this proxy for HTTPS
default: true
https_proxy:
description: HTTPS Proxy
address:
description: HTTPS address
type: domainname
params:
allow_ip: true
port:
description: HTTPS Port
type: port
default: 8080
And with this :confval:`use_for_https` boolean variable, there are two possibilities, and only two:
- The http proxy's configuration will be reused for the https proxy's configuration
- The http proxy's will not be reused for the https proxy's configuration
.. questions:: Question: shall we use the `disabled` property here?
Is it relevant to use the :term:`disabled property <disabled>` here?
**answer**: No! Because we *need* to use these variables at any :term:`context` of the proxy's manual configuration use case,
we simply have to point their values ​​in one direction or another depending on this or that context.
It is absolutely not a question of deactivating them. The `manual.https_proxy.address`
and the `manual.http_proxy.port` variables shall not be disabled (deactivated) in the manual mode.
We have to create a new property here.
The `hidden` property
----------------------
.. glossary::
hidden
A variable or family's property is hidden if its value **shall not be seen** in a given :term:`context`.
Anyway, these variables can be used again if the context evolves. This is the main difference
between the `hidden` and the `disabled` properties.
Now we can set a `hidden` property to the `https_proxy` family:
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_033/firefox/20-manual.yml
:language: yaml
:caption: The `https_proxy` subfamily with the `hidden` property
:name: HiddenPropertySubfamily
..
---
manual:
use_for_https:
description: Also use this proxy for HTTPS
default: true
https_proxy:
description: HTTPS Proxy
hidden: true
address:
description: HTTPS address
type: domainname
params:
allow_ip: true
port:
description: HTTPS Port
type: port
default: 8080
The whole `https_proxy` family has been set to `hidden` here.
.. warning:: A `hidden` variable with the `mandatory` parameter set still shall have a defined value,
even if it's hidden.
If we choose the manual proxy configuration mode,
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_033/config/03/config.yaml
:language: yaml
:caption: The Manual proxy configuration value is set
..
---
proxy_mode: Manual proxy configuration
Note that in this context, if we don't set a value to the `manual.http_proxy.address` mandatory variable, even if it is `hidden`,
Rougail will raise an error:
.. raw:: html
:url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_033/config/03/output_ro.html
:class: error-box
..
<pre>🛑 ERRORS
<span style="color: #ff0000">┣━━ </span>The following variables are mandatory but have no value:
<span style="color: #ff0000">┗━━ </span> - manual.http_proxy.address (HTTP address)
</pre>
A contextual hidden family driven by a boolean variable
-----------------------------------------------------------
What we want is having this `hidden` property assigned dynamically depending on the `use_for_https` `true` or `false` value.
Here is how to achieve this:
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_034/firefox/20-manual.yml
:language: yaml
:caption: The hidden property now depends on the value of `manual.use_for_https`
..
---
manual:
use_for_https:
description: Also use this proxy for HTTPS
default: true
https_proxy:
description: HTTPS Proxy
hidden:
variable: manual.use_for_https
address:
description: HTTPS address
type: domainname
params:
allow_ip: true
port:
description: HTTPS Port
type: port
default: 8080
Yes, it is possible to add a `variable` parameter to the `hidden` attribute.
Variable type and parameters type are copied with default value
------------------------------------------------------------------
.. discussion:: A contextualized default value
A contextualized default value is a default value (of a variable) that is driven by another variable.
This variable type and its parameters type are copied in the default value's target variable.
There is something left in the https configuration mode of the proxy:
- if the use of the proxy variables for https are the same of the proxy variables for http,
that is, if `use_for_https` is true, the https configuration variables are hidden, that's OK.
- if the use of the proxy variables for https **are not** the same of the proxy variables for http,
we would like to set their default values to the http proxy variables values.
By now, the default settings are set like this:
.. code-block:: yaml
port:
description: HTTPS Port
type: port
default: 8080
The dynamic setting of a default can be achieved in this way:
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_035/firefox/20-manual.yml
:language: yaml
:caption: A default variable's value dynamically set
..
---
manual:
use_for_https:
description: Also use this proxy for HTTPS
default: true
https_proxy:
description: HTTPS Proxy
hidden:
variable: manual.use_for_https
address:
description: HTTPS address
type: domainname
params:
allow_ip: true
default:
variable: manual.http_proxy.address
port:
description: HTTPS Port
type: port
default:
variable: manual.http_proxy.port
The default value is a pointer to another variable's value.
Here, the defaut value of `manual.https_proxy.address` points to `manual.http_proxy.address`.
This is the same thing for the default value of the `manual.https_proxy.port` variable,
which points to the `manual.http_proxy.port` value.
We also say that the default value is *calculated*.
.. glossary::
calculated
We say that a variable's value or a default variable's value is calculated
when there is a pointer which refers to another variable's value
or if there is some :term:`jinja` code or a python function that calculates it.
.. keypoints:: Key points
**Keywords**
- The :term:`hidden` property set to a family
- The fact that a property can be set dynamically
- The conditional dependency of a `hidden` property that depends on a `boolean` variable.
- A calculated default value
**Progress**
We have arrived at the end of the proxy's manual configuration's section.