diff --git a/docs/install/requirements.txt b/docs/install/requirements.txt index f0cb70858..cddeb7ea4 100644 --- a/docs/install/requirements.txt +++ b/docs/install/requirements.txt @@ -5,7 +5,7 @@ rougail-output-display==0.2.0a29 rougail-output-doc==0.2.0a45 rougail-output-formatter==0.1.0a24 rougail-output-json==0.2.0a18 -rougail-output-table==0.2.0a2 +rougail-output-table==0.1.0a2 rougail-user-data-ansible==0.1.0a5 rougail-user-data-bitwarden==0.1.0a30 rougail-user-data-commandline==0.1.0a5 diff --git a/docs/tutorial/dynfam.rst b/docs/tutorial/dynfam.rst index 2739a466d..6526af998 100644 --- a/docs/tutorial/dynfam.rst +++ b/docs/tutorial/dynfam.rst @@ -10,10 +10,26 @@ A dynamic family In a dynamically built family, instead of duplicating the definition of identical variables in several families, they can be generated automatically. -.. prerequisites:: Reminder +.. prerequisites:: Prerequisites - We handled the HTTPS mode in the previous section. But there's more modes to handle. - Let's turn back to the firefox's configuration page: + - We assume that Rougail's library is :ref:`installed ` on your computer. + + - It is possible to retrieve the current state of the various Rougail files manipulated in this tutorial step + by checking out the corresponding tag of the `rougail-tutorials` git repository. + Each tag corresponds to a stage of progress in the tutorial. + 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 `, + this workshop page corresponds to the tags :tutorial:`v1.1_060 ` to :tutorial:`v1.1_061 ` + in the repository. + + :: + + git clone https://forge.cloud.silique.fr/stove/rougail-tutorials.git + git switch --detach v1.1_060 + +We handled the HTTPS mode in the previous section. But there's more modes to handle. +Let's turn back to the firefox's configuration page: .. image:: images/soksv5.png @@ -21,9 +37,6 @@ We see that we need to handle the SOCKS configuration in addition to the HTTPS c Moreover, we can see that these two groups of variables are similar in the structure: they both have a host and a port. -Creating a generic family ----------------------------- - There are two proxies that are to be configured : - the HTTPS proxy @@ -36,9 +49,12 @@ in one shot? The interesting point here is that they are very similar in our firefox's configuration and that we can do batch processing. +Family: a dynamic family +---------------------------- + With Rougail, it is possible to create some kind of a model of family. Kind of a generic family declaration. -We call this generic family creation process a "dynamic creation" because as we will see below, +We call this generic family creation process a dynamic creation because as we will see below, these families exist at the very moment we define their **identifiers**. First, here is what we need to make (without identifiers): @@ -85,16 +101,19 @@ Now with identifiers, we have the ability to declare our families this way: port: description: "{{ identifier }} port" -What is exactly an identifier? -------------------------------- +.. index:: identifier -If you know a YAML declaration tool named Ansible, +.. type-along:: What is exactly an identifier? + +If you used the YAML declaration tool named `Ansible `_, the variable used to iterate over multiple values in a task is called an **`item`**. +We call it an identifier. -It is used in the context of a loop. For example: +It is a symbol used in the context of a loop. For example: .. code-block:: yaml - + :caption: A code example of an ansible loop + - name: Loop example with 'item' ansible.builtin.debug: msg: "The current value is {{ item }}" @@ -158,12 +177,77 @@ This identifier is a parameter that enables us to create two families named `htt When choosing a name, - rougail will put it in lowercase - - only ASCII and `_` characters are allowed. - -When we launch the rougail command line, we can have a look at the concrete families and variables that have appear: + - only ASCII and underscore ("`_`") characters are allowed. -.. code-block:: text +Here is our dynamic familiy in situation in the :file:`firefox/20-manual.yml` structure file. +.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_060/firefox/20-manual.yml + :language: yaml + :caption: The :file:`firefox/20-manual.yml` structure file with the dynamic families declaration + +.. + %YAML 1.2 + --- + version: 1.1 + + manual: + + use_for_https: true # Also use this proxy for HTTPS + + '{{ identifier }}_proxy': + description: '{{ identifier }} Proxy' + hidden: + variable: _.use_for_https + dynamic: + - HTTPS + - SOCKS + + address: + description: '{{ identifier }} address' + default: + variable: __.http_proxy.address + + port: + description: '{{ identifier }} port' + default: + variable: __.http_proxy.port + ... + +When we launch the Rougail CLI, we can see the concrete families +and variables that have been created: + +Voici le user data file sur lequel nous allons lancer la Rougail CLI: + +.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_060/config/01/config.yml + :language: yaml + :caption: In this :file:`config/01/config.yml` user data file, we assign values to variables that have been disabled + +.. + --- + proxy_mode: Manual proxy configuration + manual: + http_proxy: + address: http.proxy.net + port: 3128 + use_for_https: false + https_proxy: + address: https.proxy.net + +.. raw:: html + :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_060/config/01/cmd_ro.txt + :class: terminal + +.. + rougail -m firefox/ -u yaml -yf config/01/config.yml + + +The Rougail CLI outputs this: + +.. raw:: html + :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_060/config/01/output_ro.html + :class: output + +.. rougail -m structfile/proxy.yml -u yaml --yaml.filename userdata/proxy.yml ╭─────────────────── Caption ────────────────────╮ │ Variable Default value │ @@ -183,14 +267,16 @@ When we launch the rougail command line, we can have a look at the concrete fami ┣━━ 📓 SOCKS address: ... ┗━━ 📓 SOCKS port: ... -We can see that the dynamic family has created: +We can see that the dynamic families have been created: - an `HTTPS Proxy` family - a `SOCKS Proxy` family -as we wanted, containing an address and a port. +and, as we expected, containing an address and a port. +GWEN + .. todo:: déplacer ce hidden dans une autre page .. _conditional_hidden_family: @@ -200,7 +286,6 @@ A conditional hidden familiy Here is the final YAML version of the HTTPS and SOCKS proxy families: - We have added: - a conditional hidden family property