diff --git a/docs/install.rst b/docs/install.rst index 179cf8e50..a1258917f 100644 --- a/docs/install.rst +++ b/docs/install.rst @@ -1,7 +1,7 @@ .. _installation: -Installation -=============== +Rougail library installation +====================================== Activate you virtual environment ------------------------------------ diff --git a/docs/tutorial/preliminary.rst b/docs/tutorial/preliminary.rst index 5cea0a8e2..f695cfab0 100644 --- a/docs/tutorial/preliminary.rst +++ b/docs/tutorial/preliminary.rst @@ -14,7 +14,7 @@ Getting started - We assume that Rougail's library is :ref:`installed ` on your computer. - 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 ` to :tutorial:`v1.1_011 ` - in the repository. + in the repository: :: @@ -33,25 +33,11 @@ Creating a structure file    └── 00-proxy.yml - Let's make a :file:`rougail-tutorials` directory, with a :file:`firefox` subfolder. -- First, we wil create a :term:`structure file `, so let's create a :file:`00-proxy.yml` file +- First, we will create a :term:`structure file `, so let's create a :file:`00-proxy.yml` file located in the :file:`firefox` subfolder. .. type-along:: An empty structure 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: ` - - :: - - 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: ` .. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_000/firefox/00-proxy.yml @@ -63,24 +49,12 @@ This is an empty Rougail :term:`structure description file: ` --- version: 1.1 +:tutorial:`Download this file from the rougail-tutorials git repository ` Let's add our first variable ------------------------------ -A variable is defined at a minimum by its name. - -.. 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: ` - - :: - - git clone https://forge.cloud.silique.fr/stove/rougail-tutorials.git - git switch v1.1_010 - - Otherwise you can copy/paste this file content: +.. note:: A variable is defined at a minimum by its name. A :term:`variable` in the :term:`structure description file ` @@ -93,7 +67,7 @@ A :term:`variable` in the :term:`structure description file ` --- proxy_mode: -:download:`download this file ` +:tutorial:`Download this file from the rougail-tutorials git repository ` Let's run the Rougail CLI utility command: @@ -113,8 +87,6 @@ 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 the fact that: @@ -146,6 +118,9 @@ Let's add a variable's description, which is not mandatory but which is a good p --- proxy_mode: # Configure Proxy Access to the Internet +:tutorial:`Download this file from the rougail-tutorials git repository ` + + .. type-along:: how to set a value -- the default value We need to set a value to this `proxy_mode` variable. A first way to do it is *to set a value by default*. @@ -168,6 +143,9 @@ So let's define a variable with a description -- **and a default value** --- proxy_mode: No proxy # Configure Proxy Access to the Internet +:tutorial:`Download this file from the rougail-tutorials git repository ` + + .. type-along:: how to set a value -- the assignment @@ -219,42 +197,59 @@ he is responsible of other files called the :term:`user data file`\ s. .. exercise:: Folder structure update - Now we add a :file:`config/config.yml` file in our project:: + Now we add a :file:`config/config.yaml` file in our project:: - workplace + rougail-tutorials ├── firefox - │   ├── struct.yml + │   ├── 00-proxy.yml └── config - └── config.yml + └── config.yaml .. type-along:: how to set a value in a user datas file So for example if the integrator has not set any default value in his structure file, -the operator can do it like this: +it's up to the operator to do the job in the `config.yaml` file: -.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_003/config/02/config.yaml +.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_001/config/02/config.yaml :language: yaml - :caption: A Rougail user datas file :file:`config/config.yml`, with a default value set. + :caption: A Rougail user datas file :file:`config/config.yaml`, with a default value set. :name: RougailConfigDefaultValue .. --- proxy_mode: No proxy -With the rougail CLI the operator has to add the `-u file -ff config/config.yml` options: +:tutorial:`Download this file from the rougail-tutorials git repository ` + + +With the rougail CLI the operator has to add the `-u file -ff config/config.yaml` options: .. code-block:: text :class: terminal - :caption: A rougail Command Line Utility call with the :file:`config/config.yml` Rougail user datas file + :caption: A rougail Command Line Utility call with the :file:`config/config.yaml` Rougail user datas file - rougail -v 1.1 -m firefox -u file -ff config/01/config.yaml + rougail -m firefox -u yaml -ff config/02/config.yaml -Let us clarify this essential point: +which gives us this output: -- the integrator works on structure files -- the operator works on user data files +.. raw:: html + :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_001/config/02/output_ro.html + :class: output + +.. + 
╭──────── Caption ────────╮
+    │ Variable Modified value │
+    ╰─────────────────────────╯
+    Variables:
+    ┗━━ 📓 proxy_mode: No proxy ◀ loaded from the YAML file "config/02/config.yaml"
+
+ +.. admonition:: Important fact + + - the integrator works on structure files + - the operator works on user data files -.. note:: 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. +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. Variable's type -----------------