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

modifs

Browse source
This commit is contained in:
egarette@silique.fr 2025-11-05 06:54:03 +01:00
parent 6a87c23e2b
commit bc415deba9
5 changed files with 59 additions and 29 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

53
docs/gettingstarted.rst
View file

@ -65,6 +65,18 @@ The structure files
Rougail reads all the structure files and loads them into a single object
that represents the whole :term:`context`.
.. 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.
:name: RougailStructureFirstVariableDescription
..
%YAML 1.2
---
version: 1.1
...
.. figure:: images/schema.png
:alt: The Rougail process
:align: center
@ -96,30 +108,51 @@ The variables
-----------------
Here is a :term:`structure file` example with only a variable **variable** named `proxy_mode`
A variable can be defined with no default value at all.
A variable can be defined without other informations.
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_010/firefox/00-proxy.yml
:language: yaml
:caption: A Rougail structure file with a variable named `proxy_mode`, with a description.
:name: RougailStructureFirstVariable
..
%YAML 1.2
---
version: 1.1
proxy_mode:
...
But it's better to describe this variable:
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_011/firefox/00-proxy.yml
:language: yaml
:caption: A Rougail dictionnary file with a variable named `proxy_mode`, with a description.
:name: RougailDictionaryFirstVariableDescription
:caption: A Rougail structure file with a variable named `proxy_mode`, with a description.
:name: RougailStructureFirstVariableDescription
..
%YAML 1.2
---
proxy_mode:
description: Configure Proxy Access to the Internet
version: 1.1
proxy_mode: # Configure Proxy Access to the Internet
...
The same with a default value:
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_012/firefox/00-proxy.yml
:language: yaml
:caption: A Rougail dictionnary file with a variable named `proxy_mode`, with a default value.
:name: RougailDictionaryFirstVariableDefault
:caption: A Rougail structure file with a variable named `proxy_mode`, with a default value.
:name: RougailStructureFirstVariableDefault
..
%YAML 1.2
---
proxy_mode:
description: Configure Proxy Access to the Internet
default: No proxy
version: 1.1
proxy_mode: No proxy # Configure Proxy Access to the Internet
...
variable

2
docs/index.rst
View file

@ -30,7 +30,7 @@ Rougail
.. image:: images/logo.png
- is a `delicious cooked dish <https://fr.wikipedia.org/wiki/Rougail>`_ from the Mauritius and Reunion Islands,
- is a `delicious cooked dish <https://fr.wikipedia.org/wiki/Rougail>`_ from the Mauritius and Reunion Islands,
- it is also a `Python <https://www.python.org/>`_ library which enables us to conveniently load application :term:`variable`\ s in a simple `YAML <https://yaml.org/>`_ format in such a way that the end user consumer can handle them consistently (that is, against an user-defined consistency).

1
docs/tutorial/index.rst
View file

@ -49,4 +49,3 @@ At first glance we can see that we have a selection of five configuration option
boolean
dynfam
calculation

25
docs/tutorial/preliminary.rst
View file

@ -22,7 +22,7 @@ Making a structure file
workplace
├── firefox
   │   └── struct.yml
│   └── struct.yml
- Let's make a :file:`workplace` directory, with a :file:`firefox` subfolder.
- First, we wil make a :term:`structure file <structure file>`, so let's create a :file:`struct.yml` file
@ -42,13 +42,15 @@ This is an empty Rougail structure description file.
version: 1.1
Defining a variable and its default value
Let's create our first variable
----------------------------------------------
.. type-along:: a first variable
Let's put a variable in the Rougail :term:`structure description file <structure file>`
A variable is defined at a minimum by its name.
This is a first Rougail variable in a Rougail dictionnary:
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_010/firefox/00-proxy.yml
@ -65,7 +67,7 @@ This is a first Rougail variable in a Rougail dictionnary:
.. code-block:: text
:class: terminal
rougail -v 1.1 -m firefox/
rougail -m firefox/
we will actually have an error:
@ -78,6 +80,8 @@ we will actually have an error:
┣━━ The following variables are mandatory but have no value:
┗━━ - proxy_mode
.. FIXME on parle ici de l'option --cli.read_write ??
Because this variable is :term:`mandatory` and needs to be set **but** there's no value yet.
We can therefore deduce this result:
@ -104,8 +108,7 @@ Let's add a variable's description, which is not mandatory but which is a good p
..
---
proxy_mode:
description: Configure Proxy Access to the Internet
proxy_mode: # Configure Proxy Access to the Internet
.. type-along:: how to set a value -- the default value
@ -120,16 +123,14 @@ We need to set a value to this `proxy_mode` variable. A first way to do it is *t
So let's define a variable with a description -- **and a default value**
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/a1969abccd5e10872d4eb901a26fa16007c9fb1d/firefox/00-proxy.yml
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_012/firefox/00-proxy.yml
:language: yaml
:caption: A rougail dictionnary file with a default value for the variable
:name: RougailDictionaryVariableDefault
..
---
proxy_mode:
description: Configure Proxy Access to the Internet
default: No proxy
proxy_mode: No proxy # Configure Proxy Access to the Internet
.. type-along:: how to set a value -- the assignment
@ -187,7 +188,7 @@ he is responsible of other files called the :term:`user data file`\ s.
workplace
├── firefox
   │   ├── struct.yml
│   ├── struct.yml
└── config
└── config.yml
@ -196,7 +197,7 @@ he is responsible of other files called the :term:`user data file`\ s.
So for example if the integrator has not set any default value in his structure file,
the operator can do it like this:
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_011/config/02/config.yaml
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_012/config/02/config.yaml
:language: yaml
:caption: A Rougail user datas file :file:`config/config.yml`, with a default value set.
:name: RougailConfigDefaultValue
@ -264,7 +265,6 @@ In our firefox use case, the real type of the `proxy_mode` variable will be now
---
proxy_mode:
description: Configure Proxy Access to the Internet
type: choice
choices:
- No proxy
- Auto-detect proxy settings for this network
@ -349,7 +349,6 @@ We have the list of the possible (authorized) values:
---
proxy_mode:
description: Configure Proxy Access to the Internet
type: choice
choices:
- No proxy
- Auto-detect proxy settings for this network

7
docs/tutorial/proxymode.rst
View file

@ -1,5 +1,5 @@
Let's dive in
====================
Group variables inside families
=================================
.. objectives:: Objectives
@ -28,7 +28,6 @@ In the structure description file, we have:
---
proxy_mode:
description: Configure Proxy Access to the Internet
type: choice
choices:
- No proxy
- Auto-detect proxy settings for this network
@ -292,7 +291,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_026/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