family in turorial

docs/tutorial/index.rst

@@ -9,20 +9,19 @@ Here's a quite well supplied tutorial, we're gonna start with a use case that co
     "how to set a proxy" in the `Mozilla Firefox <https://www.mozilla.org/en-US/firefox/new/>`_ browser
     use case.
 
-More precisely, this tutorial aims at reproducing :term:`variable`\ s (that is, configuration options) behind this Mozilla Firefox settings page:
+More precisely, this tutorial aims at reproducing :term:`variable`\ s (in this use case we will call them configuration options) behind this Mozilla Firefox settings page:
 
 .. image:: images/firefox.png
 
-.. attention:: We are not coding a firefox plugin here.
+.. note:: We are not coding a firefox plugin here.
           We are just going to handle some of the firefox configuration settings
           with Rougail.
 
-
+Presentation of the firefox option configuration variables
-Presentation of the firefox configuration variables
 -----------------------------------------------------------
 
-Let's dive into the configuration validation use case,
+Let's dive into this configuration validation use case.
-that is the values entered by the user that have to be validated.
+The values entered by the user that have to be validated.
 
 At first glance we have a selection of five options configuration values that we need to fill in:
 

docs/tutorial/preliminary.rst

@@ -86,14 +86,14 @@ So, if :
 .. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_010/firefox/00-proxy.yml
    :linenos:
    :language: yaml
-   :caption: The :file:`struct/config.yaml` rougail structure file, with no default value set.
+   :caption: The :file:`firefox/00-proxy.yaml` rougail structure file, with no default value set.
    :name: RougailDictionaryNoDefault
 
 ..
     ---
     proxy_mode:
 
-In this situation there are no default value set. The rougail CLI will output an error :
+Then the rougail CLI will output an error :
 
 .. code-block:: shell
    :caption: A rougail Command Line Utility call with the :file:`config/01/config.yaml` rougail dictionnary file
@@ -111,16 +111,21 @@ In this situation there are no default value set. The rougail CLI will output an
 
 .. important:: Once defined, an option configuration :term:`value` is :term:`mandatory`.
 
-Rougail waits for a value to be set, that's why.
+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>` Tiramisu's definition.
 
-Type inference
+.. glossary::
+
+    mandatory
+
+        A variable is mandatory when a value is required, that is, `None` is not an option.
+
+Typing a variable
 -----------------
 
-By default, rougail infers a `string` type for the `proxy_mode` configuration option variable type as defined
+If the `type` attribute is not set, rougail infers a `string` type for the `proxy_mode` configuration option variable type as defined in the structure file.
-in the structure file.
+
-.
 If the operator sets an option value for example with the `number` type, like this:
 
 .. code-block:: yaml
@@ -133,10 +138,10 @@ If the operator sets an option value for example with the `number` type, like th
 Then rougail will expect a `int` or a `float` as a value for the `example_var` variable.
 In our firefox use case, the real type of the `proxy_mode` variable is a `choice` type:
 
-.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_013/config/05/config.yaml
+.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_013/firefox/00-proxy.yml
    :linenos:
    :language: yaml
-   :caption: The :file:`config/05/config.yaml` rougail dictionnary file, with a default value set.
+   :caption: The :file:`firefox/00-proxy.yml` rougail dictionnary file, with a default value set.
    :name: RougailDictionaryChoiceTypeWitheDefault
 
 ..
@@ -166,6 +171,33 @@ In our firefox use case, the real type of the `proxy_mode` variable is a `choice
     <span style="color: #5c5cff">┗━━ </span>📓 proxy_mode: <span style="color: #ffd700">No proxy</span>
     </pre>
 
+The `proxy_mode` variable here, implicitely requires a value. It is a :term:`mandatory` variable.
+
+It shall have a value, but what if the user *does not* specify any value?
+There is a possibility of setting a default value, wich is set as `No proxy` by default.
+
+Container type
+-----------------
+
+We say that the `proxy_mode` variable is *constrained* (by the `choice` type).
+
+We have the list of the possible (authorized) values:
+
+- `No proxy`
+- `Auto-detect proxy settings for this network`
+- `Use system proxy settings`
+- `Manual proxy configuration`
+- `Automatic proxy configuration URL`
+
+.. glossary::
+
+    choice type
+
+        The `proxy_mode` setting is "choice" (`type: choice`) means that
+        there is a list of available values that can be selected.
+
+.. note:: Indeed, in the Firefox configuration, it is possible to define several configuration modes,
+          from no proxy at all (`no proxy`) to a kind of automatic configuration mode from a file (`set up proxy configuration from a file`).
 
 .. keypoints:: Key points progress
 
@@ -178,6 +210,7 @@ In our firefox use case, the real type of the `proxy_mode` variable is a `choice
     - a variable's default value
     - the :term:`integrator` and :term:`operator` roles
     - a mandatory value
+    - a choice type
 
     To sum up, we have arrived at this point in writing the structure file:
 

docs/tutorial/proxymode.rst

@@ -1,25 +1,35 @@
-Firefox tutorial: the `mode_proxy` variable
-------------------------------------------------
-
 The `proxy` family
--------------------
+====================
 
-Let's create our first :term:`dictionary`.
 
-.. prerequisites:: Let's create a folder named `dict` and a dictionary file inside
+.. objectives:: Objectives
 
-We will put our dictionary files in this folder.
+   We will learn how to:
 
-Then let's put our first dictionary file in this folder, named :file:`00-proxy.yml`
+   - create a :term:`family`
+   - gather variables into a family
+   - make a variable in a variable, which is a family too
 
-.. code-block:: yaml
+
-   :caption: the :file:`00-proxy.yml` file
+.. type-along:: Reminders
+
+    - As a prerequisite we have an idea of what a :term:`structure file description <dictionary>` is.
+    - We have a :file:`firefox` folder and we are putting all the structure description files in it.
+    - We had at the :term:`structure description file <structure file>`
+
+A `manual` family
+--------------------
+
+.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_020/firefox/10-manual.yml
    :linenos:
+   :language: yaml
+   :caption: A family structure file description named `manual` in the :file:`firefox/10-manual.yml` file
+   :name: RougailFirstDictionary
 
+..
     ---
-    version: '1.1'
+    manual:
-    proxy:
+      description: Manual proxy configuration
-      description: Proxy configuration in order to have access to the internet
       type: family
 
 We can see that we have defined a :term:`family` here, and this family is *empty*
@@ -27,67 +37,66 @@ We can see that we have defined a :term:`family` here, and this family is *empty
 
 .. admonition:: If a family is empty
 
-    We need to specify the :term:`family` type (line 5) here because if we don't,
+    We need to specify the :term:`family` type here because if we don't,
     the Rougail's type engine will infer it by default as a :term:`variable`.
 
-It's because we don't have set any :term:`variable` inside.
+It's because we don't have set any :term:`variable` inside. If we make a YAML block
+(that is, if we indent), the Rougail's type inference engine will implicitely make it a family.
 
-
+.. note:: The variables, families, etc. will be created in several files for educational purposes.
-.. note:: The variables will be created in several files for educational purposes.
           Obviously all the variables can be put in the same file.
 
+A family inside a family
+----------------------------
 
-The proxy's configuration type
+Creating a family hierarchy is very easy, here is an example
-----------------------------------
 
-In the Firefox configuration, it is possible to define several configuration modes,
+.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_021/firefox/10-manual.yml
-from no proxy at all (`no proxy`) to a kind of automatic configuration mode from a file (`set up proxy configuration from a file`).
+   :linenos:
+   :language: yaml
+   :caption: A rougail structure description file with a hierarchy.
+   :name: RougailFirstFamilyHierarchy
+
+..
+    ---
+    manual:
+      description: Manual proxy configuration
+      type: family
+
+      http_proxy:
+        description: HTTP Proxy
+        type: family
+
+Here the `http_proxy` family lives inside the `manual` family.
+
+Put a variable inside a family or a sub family
+--------------------------------------------------
 
 Let's create a variable in its family with a description and a default value.
 The type of this variable is a `choice` type:
 
-.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_006/firefox/00-proxy.yml
+.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_022/firefox/10-manual.yml
    :linenos:
    :language: yaml
-   :caption: A rougail dictionnary file with a choice variable named `proxy_mode`, with a default value and a description.
+   :caption: An `address` variable in the `http_proxy` family
-   :name: RougailDictionaryFirstVariableChoiceType
+   :name: RougailVariableInSubFamily
 
-.. glossary::
+..
+    ---
+    manual:
+      description: Manual proxy configuration
+      type: family
 
-    mandatory
+      http_proxy:
+        description: HTTP Proxy
+        type: family
 
-        A variable is mandatory when a value is required, that is, `None` is not an option.
+        address:
+          description: HTTP address
 
-The `proxy_mode` variable here, implicitely requires a value. It is a mandatory variable.
+.. keypoints:: Key points progress
 
-It shall have a value, but what if the user *does not* specify any value?
+    **Keywords**
-There is a possibility of setting a default value, wich is set as `No proxy` by default.
-
-.. glossary::
-
-    choice type
-
-        The `proxy_mode` setting is "choice" (`type: choice`) means that
-        there is a list of available values that can be selected.
-
-We say that the `proxy_mode` variable is *constrained* (by the `choice` type).
-
-We have the list of the possible (authorized) values:
-
-- `No proxy`
-- `Auto-detect proxy settings for this network`
-- `Use system proxy settings`
-- `Manual proxy configuration`
-- `Automatic proxy configuration URL`
-
-Now let's test our first two dictionaries:
-
->>> from rougail import Rougail, RougailConfig
->>> from pprint import pprint
->>> RougailConfig['dictionaries_dir'] = ['dict']
->>> rougail = Rougail()
->>> config = rougail.get_config()
->>> config.property.read_only()
->>> pprint(config.value.get(), sort_dicts=False)
-{'rougail.proxy.proxy_mode': 'No proxy'}
 
+    - :term:`family`, and sub families
+    - variables defined in a family