doc(improvement)

docs/abstract.rst

@@ -176,7 +176,7 @@ Here is a reminder of the different steps:
      - - Operator
        - Integrator
 
-Variable lifetime
+Variable lifecyle
 ----------------------
 
 Rougail's a configuration language and data validation tool is designed 
@@ -184,14 +184,14 @@ to simplify defining, validating, and generating structured configuration and da
 
 Rougail aims at defining variables.
 
-Here we are talking about the variable lifetime.
+Here we are talking about the variable lifecyle.
 
-The variable’s lifetime is the period between its creation and its destruction.
+The variable’s lifecyle is the period between its creation and its destruction.
 
 The lifecycle of a variable includes the generic stages (like, in the C language):
 
 - Creation: variables are assigned a name and a type
-- Initialization: they are assigned their first value
+- Initialization: they are assigned their first value (we call it :term:`default value`)
 - Assignment: the variable's value is modified
 - Reading: the variable's value is used
 - Destruction: the variable terminates upon the destruction of the object
@@ -207,7 +207,7 @@ But other concepts are included in the lifecycle:
 
    * - **Step**
      - Actor
-     - Lifetime
+     - Lifecyle
 
    * - **Structured data**
      - Integrator
@@ -257,7 +257,7 @@ Variable definition settings are immutable.
 
    * - **Step**
      - Actor
-     - Lifetime
+     - Lifecyle
      - Mutability
 
    * - **Structured data**
@@ -304,7 +304,7 @@ The configuration is said to be in :term:`read only mode`.
 
    * - **Step**
      - Actor
-     - Lifetime
+     - Lifecyle
      - Mutability
      - Value
 
@@ -380,7 +380,7 @@ A picture is worth a thousand words:
 
    * - **Step**
      - Actor
-     - Lifetime
+     - Lifecyle
      - Mutability
      - Value
      - Access control

docs/index.rst

@@ -57,6 +57,7 @@ Rougail
    :titlesonly:
    :caption: User data
 
+   user_data/prerequisites
    user_data/index
 
 .. toctree::

docs/structured_data.rst

@@ -178,3 +178,10 @@ There is an execption. That what we call the short-hand declaration.
         Of course, it's not possible to fully customize the variable with this notation.
 
         Use shorthand notation whenever possible. This makes the file easier to read.
+
+Versioned
+---------
+
+The format can evolve. This means that parameters can be added, removed, or modified.
+When writing structured data, you must always specify the format version.
+You must also ensure that your Rougail version is compatible with your format version.

docs/structured_data/data_integrity.rst

@@ -96,6 +96,18 @@ For certain types, there are a number of parameters that can be used to further
 
 .. _nullable_variable:
 
+Custom type
+'''''''''''
+
+It is not possible to create every possible type of variable.
+
+Therefore, it is necessary to provide a simple way to create these custom types.
+
+There are two ways to create a type:
+
+- creating a :term:`Tiramisu` type
+- creating a type from an existing variable, see the tutorial with a real world sample :doc:`custom type <../tutorial/customtype>`.
+
 Nullable variable
 '''''''''''''''''
 

docs/user_data/ansible.rst

@@ -1,14 +1,16 @@
 Load user data from Ansible compatible file
 ===========================================
 
+Synopsis
+-------------
+
 .. note::
 
     | Ansible offers a tool (ansible-vault) for encrypting inventory files. With this user data you can open an encrypt inventory file. This is a perfect way to manage a smooth migration from Ansible inventory to Rougail. Or it could be a way to encrypt these secrets in a file with a secure format.
-    | **Path**: ansible
-    | `*disabled*`
     | **Disabled**: if ansible is not set in "select for user data" (step.user_data).
 
-
+Parameters
+--------------
 
 .. list-table::
 

docs/user_data/bitwarden.rst

@@ -1,14 +1,16 @@
 Load user data secrets from Bitwarden
 =====================================
 
+Synopsis
+-------------
+
 .. note::
 
     | Load the secrets from Bitwarden (or a compatible server like Vaultwarden). The data is retrieved using the official command line "bw" or the alternative command "rbw" (faster). Before using Rougail, the command must be logged and unlocked.
-    | **Path**: bitwarden
-    | `*disabled*`
     | **Disabled**: if bitwarden is not set in "select for user data" (step.user_data).
 
-
+Parameters
+--------------
 
 .. list-table::
 

docs/user_data/commandline.rst

@@ -1,6 +1,9 @@
 Load user data from commandline parser
 =======================================
 
+Synopsis
+-------------
+
 .. note::
 
     | Load the user data from the current command line.

docs/user_data/environment.rst

@@ -1,6 +1,9 @@
 Load user data from environment variables
 =========================================
 
+Synopsis
+-------------
+
 .. note::
 
     | Variable values can be defined directly from an environment variable.
@@ -10,11 +13,10 @@ Load user data from environment variables
     | Note that variable paths can contain dots ("."), which are not permitted everywhere. To avoid any issues, use the `env` command, for example: `env ROUGAIL_MY_FAMILY.MY_VARIABLE=1 rougail`.
     | 
     | For values, there is no difference between a number and a letter (they can be enclosed in quotes or not). However, booleans are True or False. The separator for multiple variables is a comma.
-    | **Path**: environment
-    | `*disabled*`
     | **Disabled**: if environment is not set in "select for user data" (step.user_data).
 
-
+Parameters
+--------------
 
 .. list-table::
 

docs/user_data/example.yaml

@@ -0,0 +1,53 @@
+%YAML 1.2
+---
+version: 1.1
+
+person:  # Description of a person
+
+
+  firstname:  # Last name of the person
+
+  lastnames: []  # Last names of the person
+
+  age:
+    description: Person's age
+    type: integer
+    params:
+      min_integer: 0
+      max_integer: 120
+
+  legal_age:
+    description: The person is of legal age
+    type: boolean
+    default:
+      jinja: |-
+        {{ _.age is not none and _.age >= 18 }}
+    hidden: true
+
+  drive_license:
+    description: The person has a driver's license
+    default: false
+    disabled:
+      variable: _.legal_age
+      when_not: true
+
+  means_of_transport:
+    description: Means of transport used by the person
+    choices:
+      - human-powered
+      - public transport
+      - electric-assisted vehicle
+      - engine-powered without a license
+      - engine-powered
+      - others
+    validators:
+      - jinja: |-
+          {% if _.means_of_transport == "engine-powered" %}
+            {% if _.drive_license is propertyerror %}
+              {{ _.lastnames[0] }} {{ _.firstname }} is not of legal age but declares that he uses an engine-powered
+            {% elif not _.drive_license %}
+              {{ _.lastnames[0] }} {{ _.firstname }} does not have a license but declares that he uses an engine-powered
+            {% endif %}
+          {% endif %}
+        description: Engine-powered are only permitted for individuals with a driver's license
+...

docs/user_data/prerequisites.rst

@@ -0,0 +1,59 @@
+Prerequisites
+=============
+
+Installation
+------------
+
+We assume that Rougail's command line is :ref:`installed <installation>` on your computer.
+
+Verify that you have correctly installed the tool by running:
+
+.. code-block:: bash
+   :class: terminal 
+
+
+        $ rougail --cli.versions
+        tiramisu: x.x.x
+        tiramisu-cmdline-parser: x.x.x
+        rougail: x.x.x
+        rougail-cli: x.x.x
+        rougail-user-data-ansible: x.x.x
+        rougail-user-data-bitwarden: x.x.x
+        rougail-user-data-commandline: x.x.x
+        rougail-user-data-environment: x.x.x
+        rougail-user-data-questionary: x.x.x
+        rougail-user-data-yaml: x.x.x
+        rougail-output-ansible: x.x.x
+        rougail-output-display: x.x.x
+        rougail-output-doc: x.x.x
+        rougail-output-formatter: x.x.x
+        rougail-output-json: x.x.x
+        rougail-output-table: x.x.x
+
+Smoke test
+----------
+
+We need a Rougail structured data file to test and illustrate the different user data loading modules.
+
+.. literalinclude:: example.yaml
+   :caption: A example of structured data file place in the :file:`example.yaml` structure file
+
+Let's test this structured file:
+
+.. code-block:: bash
+   :class: terminal 
+
+        $ rougail -m example.yaml
+
+The output has to be:
+
+.. raw:: html
+    :class: terminal
+
+        <span style="font-weight: bold; color: #ff0000">🛑 Caution</span>
+        <span style="color: #ff0000">┗━━ </span>Description of a person
+        <span style="color: #ff0000">    </span><span style="color: #ff0000">┣━━ </span>Last name of the person: <span style="color: #ff0000">🛑 mandatory variable but has no value</span>
+        <span style="color: #ff0000">    </span><span style="color: #ff0000">┣━━ </span>Last names of the person: <span style="color: #ff0000">🛑 mandatory variable but has no value</span>
+        <span style="color: #ff0000">    </span><span style="color: #ff0000">┣━━ </span>Person's age: <span style="color: #ff0000">🛑 mandatory variable but has no value</span>
+        <span style="color: #ff0000">    </span><span style="color: #ff0000">┗━━ </span>Means of transport used by the person: <span style="color: #ff0000">🛑 mandatory variable but has no value</span>
+

docs/user_data/questionary.rst

@@ -1,14 +1,16 @@
 Define user data interactively in the console
 =============================================
 
+Synopsis
+-------------
+
 .. note::
 
     | The user will enter variable values in a command-line interface. The variables will be displayed one after another, allowing the user to change or add values.
-    | **Path**: questionary
-    | `*disabled*`
     | **Disabled**: if questionary is not set in "select for user data" (step.user_data).
 
-
+Parameters
+--------------
 
 .. list-table::
 

docs/user_data/yaml.rst

@@ -1,14 +1,22 @@
-Charge user data from YAML file
-===============================
+Load user data from YAML file
+=============================
+
+Synopsis
+-------------
 
 .. note::
 
-    | **Path**: yaml
-    | `*disabled*`
+    | Variable values can be defined in a list of YAML files.
     | **Disabled**: if yaml is not set in "select for user data" (step.user_data).
 
+Sample
+------
 
 
+
+Parameters
+--------------
+
 .. list-table::
 
    * - Variable
@@ -61,4 +69,3 @@ Charge user data from YAML file
        - last
 
        - none
-