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

added git repo links

Browse source
This commit is contained in:
gwen 2025-11-07 09:05:44 +01:00
parent aca97a3e92
commit a0e556e7c1
4 changed files with 83 additions and 46 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

33
docs/library/user_datas.rst
View file

@ -81,9 +81,7 @@ Here is the script which is load user data from the YAML file:
rougail = Rougail()
config = rougail.run()
user_datas = RougailUserDataYaml(
config,
).run()
user_datas = RougailUserDataYaml(config).run()
rougail.user_datas(user_datas)
print(config.value.get())
@ -135,8 +133,9 @@ Environment variables
We can define use data from environment variables. The environment name is a "prefix" (ROUGAIL by default) with "_" and variable name in uppercase format.
For example:
- my_variable has ROUGAIL_MY_VARIABLE as a environment variable name
- my_family.my_variable has ROUGAIL_MY_FAMILY.MY_VARIABLE as a environment variable name
- `my_variable` has `ROUGAIL_MY_VARIABLE` as a environment variable name
- `my_family.my_variable` has `ROUGAIL_MY_FAMILY.MY_VARIABLE` as a environment variable name
Some shell doesn't allow dot in environment file. In this case use the command "env".
@ -156,9 +155,7 @@ Here is the script:
rougail = Rougail()
config = rougail.run()
user_datas = RougailUserDataEnvironment(
config,
).run()
user_datas = RougailUserDataEnvironment(config).run()
rougail.user_datas(user_datas)
print(config.value.get())
@ -184,9 +181,7 @@ We can redefine the prefix with `environment.default_environment_name` (prefix i
rougail = Rougail()
config = rougail.run()
user_datas = RougailUserDataEnvironment(
config,
).run()
user_datas = RougailUserDataEnvironment(config).run()
rougail.user_datas(user_datas)
print(config.value.get())
@ -211,9 +206,7 @@ If you define a `main_namespace` or `extra_namespaces`, the `environment.default
rougail = Rougail()
config = rougail.run()
user_datas = RougailUserDataEnvironment(
config,
).run()
user_datas = RougailUserDataEnvironment(config).run()
rougail.user_datas(user_datas)
print(config.value.get())
@ -240,9 +233,7 @@ This is why the `environment.with_secrets` parameter allows you to reject secret
rougail = Rougail()
config = rougail.run()
user_datas = RougailUserDataEnvironment(
config,
).run()
user_datas = RougailUserDataEnvironment(config).run()
rougail.user_datas(user_datas)
print(config.value.get())
@ -300,6 +291,7 @@ Let's execute `script.py` to display help:
And now with modified value:
.. code-block:: bash
$ python script.py --my_variable "a new value" --no-my_boolean_variable --my_integer_variable 10 --my_secret_variable MyVeryStrongPassword
{<TiramisuOption path="my_variable">: 'a new value', <TiramisuOption path="my_boolean_variable">: False, <TiramisuOption path="my_integer_variable">: 10, <TiramisuOption path="my_secret_variable">: 'MyVeryStrongPassword'}
@ -338,12 +330,14 @@ You can combine user datas, for example if you want to load datas from environme
Let's execute `script.py` with environment variable and commandline arguments:
.. code-block:: bash
$ env ROUGAIL_MY_VARIABLE="a new value" ROUGAIL_MY_BOOLEAN_VARIABLE="False" python script.py --my_integer_variable 10 --my_secret_variable MyVeryStrongPassword
{<TiramisuOption path="my_variable">: 'a new value', <TiramisuOption path="my_boolean_variable">: False, <TiramisuOption path="my_integer_variable">: 10, <TiramisuOption path="my_secret_variable">: 'MyVeryStrongPassword'}
If the value of a variable is define with an environment variable and commandline argument, the value is the value of the last user data define:
.. code-block:: bash
$ env ROUGAIL_MY_VARIABLE="not a new" python script.py --my_variable "a new value" --no-my_boolean_variable --my_integer_variable 10 --my_secret_variable MyVeryStrongPassword
{<TiramisuOption path="my_variable">: 'a new value', <TiramisuOption path="my_boolean_variable">: False, <TiramisuOption path="my_integer_variable">: 10, <TiramisuOption path="my_secret_variable">: 'MyVeryStrongPassword'}
@ -373,6 +367,7 @@ Recreate a script with environnement variable support which is display the retur
Try to load the value an unknown variable:
.. code-block:: bash
$ env ROUGAIL_UNKNOWN_VARIABLE="a value" python script.py
{'errors': [], 'warnings': ['variable or family "unknown_variable" does not exist, it will be ignored when loading from environment variable']}
@ -381,13 +376,15 @@ As you can see, a warnings is return.
Try to load the value of an hidden variable:
.. code-block:: bash
$ env ROUGAIL_MY_HIDDEN_VARIABLE="a value" python script.py
{'errors': [], 'warnings': ['variable "my_hidden_variable" (My hidden variable) is hidden, it will be ignored when loading from environment variable']}
Finally if a try to change the value of a secret, which is not allowed:
.. code-block:: bash
$ env ROUGAIL_MY_SECRET_VARIABLE="MyVeryStrongPassword" python script.py
{'errors': ['the variable "my_secret_variable" contains secrets and should not be defined in environment variable'], 'warnings': []}
An error is generate.
An error is generated.

5
docs/structfile.rst
View file

@ -19,6 +19,11 @@ Definition
The header of a structure file
-----------------------------------
A basic structure file is composed of:
- a YAML 1.2 standard header
- a version attribute
.. 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.

5
docs/tutorial/index.rst
View file

@ -46,6 +46,11 @@ We'll learn in this tutorial how to set the values of the configuration options
It is advisable to follow this tutorial with the help of the corresponding :tutorial:`Rougail git repository tutorial <>`.
If you use this rougail tutorial repository, you will have all the necessary files distributed in the correct tree structure.
::
git clone https://forge.cloud.silique.fr/stove/rougail-tutorials.git
Of course, you can also decide to start from scratch and copy/paste the tutorial files content.
.. toctree::

86
docs/tutorial/preliminary.rst
View file

@ -5,36 +5,54 @@ Getting started
We will learn how to:
- create a Rougail :term:`structure description file <structure file>`
- define a Rougail :term:`structure file format version <structure file>`
- define a Rougail :term:`variable` and set its :term:`value`
- create a :term:`structure description file <structure file>`
- add a :term:`structure file format version <structure file>`
- add a :term:`variable` and set its :term:`value`
.. prerequisites:: Prerequisites
- We assume that Rougail's library is :ref:`installed <installation>` on your computer.
- If you want to follow with this tutorial with the help of the corresponding :tutorial:`Rougail tutorial git repository <>`,
this workshop page corresponds to the tags v1.1_000 to v1.1_004.
.. of :tutorial:`the Git repository <src/tag/v1.1_001>`.
- If you want to follow with this tutorial with the help of the corresponding :tutorial:`Rougail-tutorials git repository <>`,
this workshop page corresponds to the tags :tutorial:`v1.1_000 <src/tag/v1.1_000>` to :tutorial:`v1.1_011 <src/tag/v1.1_011>`
in the repository.
Making a structure file
-------------------------
::
git clone https://forge.cloud.silique.fr/stove/rougail-tutorials.git
git switch v1.1_000
Creating a structure file
--------------------------
.. demo:: The folder structure
Here is the tree structure we want to have::
workplace
├── firefox
│   └── struct.yml
rougail-tutorials
└── firefox
   └── 00-proxy.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
- Let's make a :file:`rougail-tutorials` directory, with a :file:`firefox` subfolder.
- First, we wil create a :term:`structure file <structure file>`, so let's create a :file:`00-proxy.yml` file
located in the :file:`firefox` subfolder.
.. type-along:: An empty structure file
This is an empty Rougail structure description file.
.. note::
If you don't want to manualy create a file in your favorite text editor
and prefer to start with a ready-made project, you can clone the
:tutorial:`v1.1_000 version of the rougail-tutorials git repository: <src/tag/v1.1_000>`
::
git clone https://forge.cloud.silique.fr/stove/rougail-tutorials.git
git switch v1.1_000
Otherwise you can copy/paste this file content:
This is an empty Rougail :term:`structure description file: <structure file>`
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_000/firefox/00-proxy.yml
:language: yaml
@ -46,20 +64,29 @@ This is an empty Rougail structure description file.
version: 1.1
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>`
Let's add our first variable
------------------------------
A variable is defined at a minimum by its name.
This is a first Rougail variable in a Rougail dictionnary:
.. note::
If you don't want to manualy create a file in your favorite text editor
and prefer to start with a ready-made project, you can clone the
:tutorial:`v1.1_010 version of the rougail-tutorials git repository: <src/tag/v1.1_010>`
::
git clone https://forge.cloud.silique.fr/stove/rougail-tutorials.git
git switch v1.1_010
Otherwise you can copy/paste this file content:
A :term:`variable` in the :term:`structure description file <structure file>`
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_001/firefox/00-proxy.yml
:language: yaml
:caption: A Rougail dictionnary file with only one variable
:caption: A Rougail structure file with only one variable
:name: RougailDictionaryFirstVariableName
..
@ -68,7 +95,7 @@ This is a first Rougail variable in a Rougail dictionnary:
:download:`download this file <https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_001/firefox/00-proxy.yml>`
- If we run the Rougail CLI utility command
Let's run the Rougail CLI utility command:
.. code-block:: text
:class: terminal
@ -90,20 +117,23 @@ we will actually have an error:
Because this variable is :term:`mandatory` and needs to be set **but** there's no value yet.
We can therefore deduce this result:
We can therefore deduce the fact that:
.. note:: Once defined, an option configuration :term:`value` is :term:`mandatory`.
.. admonition:: Fact
Once defined, an option configuration :term:`value` is :term:`mandatory`.
That is to say, it is absolutely necessary to assign a value to this variable.
Rougail waits for the `proxy_mode` configuration option's value to be set.
.. seealso:: To go further, have a look at the :tiramisu:`mandatory option <glossary.html#term-mandatory-option>` according to the definition of Tiramisu.
.. glossary::
mandatory
A variable is mandatory when a value is required, that is, `None` is not a possible value.
It **must** have a defined value.
.. seealso:: To go further, have a look at the :tiramisu:`mandatory option <glossary.html#term-mandatory-option>` according to the definition of Tiramisu.
Let's add a variable's description, which is not mandatory but which is a good practice: