code(VaC): complet the explaination

docs/conf.py

@@ -31,7 +31,7 @@ release = '1.0'
 
 extensions = [
         'sphinx.ext.extlinks', 'sphinx_lesson', 'sphinx.ext.todo',
-        'ext.xref', 'ext.extinclude'
+        'ext.xref', 'ext.extinclude', 'sphinxnotes.strike',
 ]
 
 #---- disable highlight warnings with yaml new version ----

docs/readme.txt

@@ -14,6 +14,7 @@ Then install the sphinx libraries::
     ./.venv/bin/pip3 install sphinx
     ./.venv/bin/pip3 install sphinx_rtd_theme
     ./.venv/bin/pip3 install sphinx_lesson
+    ./.venv/bin/pip3 install sphinxnotes
 
 
 The generatef html output is located in the `docs/build/html` subfolder,

docs/vac.rst

@@ -23,6 +23,15 @@ and even more annoying to add new variables.
 
 Variables can be redundant and sometimes are defined on several places.
 
+.. attention::
+
+    Many IaC projects use what could be called Values as Code (User Data as Code with the Rougail terminology).
+    Values are placed in a versioned and structured repositories.
+    But we don't share the variable itself (apart from its name).
+    We are thinking of its type, its scope, its purpose, etc.
+
+    Variables as Code is not only the values.
+
 Reusable and shareable variables
 ------------------------------------
 
@@ -59,4 +68,139 @@ Once defined, variables must be able to:
 - display and archive the final values in a readable format
 - allow other applications to use these variables
 
+Variables as Code with Rougail by example
+-------------------------------------------
 
+There's nothing better than a simple example to illustrate everything that's just been presented.
+
+Structured file
+~~~~~~~~~~~~~~~~~~
+
+Let's start by creating a file in Rougail format.
+
+This isn't the time to explain the format.
+
+But we'll create a quick file here to create the "my_variable" variable:
+
+.. code-block:: yaml
+
+    %YAML 1.2
+    ---
+    version: 1.1
+
+    my_variable: my_value  # It's my variable
+    ...
+
+Let's document it
+''''''''''''''''''''
+
+We can start by generating the variable's documentation from this file:
+
+.. list-table::
+
+   * - Variable
+     - Description
+
+   * - **my_variable**
+
+       `string <https://rougail.readthedocs.io/en/latest/variable.html#variables-types>`__ `mandatory`
+     - It's my variable.
+
+       **Default**: my_value
+
+Or an example user data file in YAML format:
+
+**Example with all variables modifiable:**
+
+.. code-block:: yaml
+
+   ---
+   my_variable: my_value
+
+Regarding documentation, it's even possible to generate a changelog view for users.
+
+Let's imagine that the default value was originally `old_value` and is now `my_value`:
+
+.. list-table::
+
+   * - Variable
+     - Description
+
+   * - **my_variable**
+
+       `string <https://rougail.readthedocs.io/en/latest/variable.html#variables-types>`__ `mandatory`
+     - It's my variable.
+
+       **Default**: :strike:`old_value` **myvalue**
+
+Now it's time to export
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+In simple JSON format:
+
+.. code-block:: json
+
+    {
+      "my_variable": "my_value"
+    }
+
+Or in advanced Ansible format:
+
+.. code-block:: json
+
+    {
+      "_meta": {
+        "hostvars": {
+          "host1.net": {
+            "ansible_host": "host1.net",
+            "inventory": {
+              "my_variable": "my_value"
+            }
+          }
+        }
+      },
+      "app1": {
+        "hosts": [
+          "host1.net"
+        ]
+      }
+    }
+
+Or display it
+~~~~~~~~~~~~~~~~
+
+Displaying informations is an important step in the VaC approach. In a complex environment where variables are defined in multiple places, not to mention their values located elsewhere, maintaining good traceability of variables and their values becomes difficult.
+
+Managing variables like code also means `compiling` the informations.
+
+Here display our examples:
+
+.. raw:: html
+   :class: output
+
+    <pre>
+    ╭─────── Caption ────────╮
+    │ Variable <span style="color: #ff7300">Default value</span> │
+    ╰────────────────────────╯
+    Variables:
+    <span style="color: #5c5cff">┗━━ </span>📓 It's my variable: <span style="color: #ff7300">my_value</span>
+    </pre>
+
+Now change the value with differents user data:
+
+.. raw:: html
+   :class: output
+
+    <pre>
+    ╭────────────── Caption ───────────────╮
+    │ Variable <span style="color: #00aa00">Modified value</span>              │
+    │          (⏳ Original default value) │
+    ╰──────────────────────────────────────╯
+    ╭──────────── Layers ─────────────╮
+    │ • the YAML file "user_data.yml" │
+    │ • environment variable          │
+    │ • Questionary                   │
+    ╰─────────────────────────────────╯
+    Variables:
+    <span style="color: #5c5cff">┗━━ </span>📓 It's my variable: <span style="color: #00aa00">I am right about the value</span> ◀ loaded from questionary <br/>(⏳ I define the value! ◀ loaded from environment variable <br/>⏳ no it's my value ◀ loaded from the YAML file "user_data.yml" <br/>⏳ my_value)
+    </pre>