docs(v1.1_120): examples parameter

docs/tutorial/examples.rst

@@ -0,0 +1,94 @@
+A full documented variable 
+==============================
+
+.. objectives:: Objectives
+   
+   You’ve no doubt wondered, on more than one occasion, how to do this or that; 
+   even if you have the documentation, it’s not clear enough. 
+   
+   What would make it clear is a good example.
+   
+   With Rougail, you can add examples into the structural specifications of a variable or a family, illustrative examples.
+   That is what we will look at in this section. Documentation through examples.
+
+.. prerequisites:: Prerequisites
+
+    - We assume that Rougail's library is :ref:`installed <installation>` 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 <src/branch/1.1>`,
+    this workshop page corresponds to the tags :tutorial:`v1.1_120 <src/tag/v1.1_120/README.md>` to :tutorial:`v1.1_121 <src/tag/v1.1_121/README.md>`
+    in the repository.
+
+    ::
+
+       git clone https://forge.cloud.silique.fr/stove/rougail-tutorials.git
+       git switch --detach v1.1_120
+
+
+Examples
+-----------
+
+All you need to do is add an `examples` parameter to the structural definition of our variable.
+
+
+.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_120/firefox/40-no_proxy.yml
+   :language: yaml
+   :caption: The :file:`firefox/40-no_proxy` structure definition file with an `example` parameter
+
+.. 
+    %YAML 1.2
+    ---
+    version: 1.1
+
+    no_proxy:
+      description: Address for which proxy will be desactivated
+      examples:
+        - .mozilla.org
+        - .net.nz
+        - 192.168.1.0/24
+      type: domainname
+      params:
+        allow_ip: true
+        allow_cidr_network: true
+        allow_without_dot: true
+        allow_startswith_dot: true
+      multi: true
+      mandatory: false
+      disabled:
+        variable: _.proxy_mode
+        when: No proxy
+    ...
+
+.. raw:: html
+   :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_120/config/02/cmd_ro.txt
+   :class: terminal
+
+..
+    rougail -m firefox/ --types types/proxy -u yaml -yf config/02/config.yml
+
+
+
+.. raw:: html
+   :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_120/config/02/output_ro.html
+   :class: output
+
+..
+    ╭────────────── Caption ───────────────╮
+    │ Variable Modified value              │
+    │          (⏳ Original default value) │
+    ╰──────────────────────────────────────╯
+    Variables:
+    ┣━━ 📓 Configure Proxy Access to the Internet: Automatic proxy configuration URL
+    ┃   ◀ loaded from the YAML file "config/02/config.yml" (⏳ No proxy)
+    ┣━━ 📓 Automatic proxy configuration URL: https://auto.proxy.net/wpad.dat ◀ 
+    ┃   loaded from the YAML file "config/02/config.yml"
+    ┗━━ 📓 Address for which proxy will be desactivated:
+        ┣━━ example.net ◀ loaded from the YAML file "config/02/config.yml"
+        ┗━━ 192.168.1.0/24 ◀ loaded from the YAML file "config/02/config.yml"
+
+

docs/tutorial/index.rst

@@ -58,4 +58,5 @@ Let's dive into this **configuration options validation** use case.
    customtype
    nullable
    multiple
+   examples
    whatsnext

docs/variable.rst

@@ -35,7 +35,7 @@ Variable name
 
 .. seealso::
 
-    Have a look at the :ref:`convention on variable naming link <convention on variable names>`.
+    Have a look at the :ref:`convention on variable naming link <namingconvention>`.
 
 Variable's types
 -----------------
@@ -183,7 +183,7 @@ Parameters
    * - **unique**
 
        `boolean`
-     - The :term:`multiple` type variable accepts the same value several times. If unique is set to `false`, a :term:`multiple` variable only accepts the same value once in the list.
+     - The :term:`multiple <multi>` type variable accepts the same value several times. If unique is set to `false`, a :term:`multiple <multi>` variable only accepts the same value once in the list.
 
        **Default value**: `false`
    * - **hidden**