dynfam

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

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.
+    - We assume that Rougail's library is :ref:`installed <installation>` on your computer.
-   Let's turn back to the firefox's configuration page:
+
+    - 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 <src/branch/1.1>`, 
+    this workshop page corresponds to the tags :tutorial:`v1.1_060 <src/tag/v1.1_060>` to :tutorial:`v1.1_061 <src/tag/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,15 +101,18 @@ 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 <https://docs.ansible.com>`_, 
 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:
@@ -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.
+               - only ASCII and underscore ("`_`") characters are allowed.
 
-When we launch the rougail command line, we can have a look at the concrete families and variables that have appear:
+Here is our dynamic familiy in situation in the :file:`firefox/20-manual.yml` structure file.
 
-.. code-block:: text
+.. 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