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

configuration and user data file in preliminary

Browse source
This commit is contained in:
gwen 2025-12-01 18:16:24 +01:00
parent 50bf8e696d
commit cb9b534669
3 changed files with 74 additions and 45 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

96
docs/tutorial/family.rst
View file

@ -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 <src/branch/1.1>`,
this workshop page corresponds to the tags :tutorial:`v1.1_020 <src/tag/v1.1_020>` in the repository:
this workshop page corresponds to the tags :tutorial:`v1.1_020 <src/tag/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 <namingconvention>`.
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 <src/tag/v1.1_021/firefox/00-proxy.yml>`
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 <value>` to the :confval:`address` variable
:tutorial:`Download this file from the rougail-tutorials git repository <src/tag/v1.1_022/firefox/10-manual.yml>`
So we have now an :confval:`address` variable:
Now that the :confval:`address` variable is declared, the :term:`operator` can set :term:`a value <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:
<span style="color: #ff0000">┗━━ </span> - manual.http_proxy.address (HTTP address)
</pre>
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

BIN
docs/tutorial/images/firefox_manual_family.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 32 KiB

23
docs/tutorial/preliminary.rst
View file

@ -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`