From bc415deba99a6ad9dd50a4563ccdb4d6c0610d16 Mon Sep 17 00:00:00 2001 From: Emmanuel Garette Date: Wed, 5 Nov 2025 06:54:03 +0100 Subject: [PATCH] modifs --- docs/gettingstarted.rst | 53 ++++++++++++++++++++++++++++------- docs/index.rst | 2 +- docs/tutorial/index.rst | 1 - docs/tutorial/preliminary.rst | 25 ++++++++--------- docs/tutorial/proxymode.rst | 7 ++--- 5 files changed, 59 insertions(+), 29 deletions(-) diff --git a/docs/gettingstarted.rst b/docs/gettingstarted.rst index dd0731f18..8ad3a3ffe 100644 --- a/docs/gettingstarted.rst +++ b/docs/gettingstarted.rst @@ -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 diff --git a/docs/index.rst b/docs/index.rst index 92f638bdd..0183508aa 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -30,7 +30,7 @@ Rougail .. image:: images/logo.png -- is a `delicious cooked dish `_ from the Mauritius and Reunion Islands, +- is a `delicious cooked dish `_ from the Mauritius and Reunion Islands, - it is also a `Python `_ library which enables us to conveniently load application :term:`variable`\ s in a simple `YAML `_ format in such a way that the end user consumer can handle them consistently (that is, against an user-defined consistency). diff --git a/docs/tutorial/index.rst b/docs/tutorial/index.rst index 8cd12de02..08331aa98 100644 --- a/docs/tutorial/index.rst +++ b/docs/tutorial/index.rst @@ -49,4 +49,3 @@ At first glance we can see that we have a selection of five configuration option boolean dynfam calculation - diff --git a/docs/tutorial/preliminary.rst b/docs/tutorial/preliminary.rst index 136ea7f6d..f25974001 100644 --- a/docs/tutorial/preliminary.rst +++ b/docs/tutorial/preliminary.rst @@ -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 `, 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 ` +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 diff --git a/docs/tutorial/proxymode.rst b/docs/tutorial/proxymode.rst index e9890a66e..43869edb2 100644 --- a/docs/tutorial/proxymode.rst +++ b/docs/tutorial/proxymode.rst @@ -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