doc(variable): adjust parameters

docs/family.rst

@@ -70,75 +70,96 @@ Parameters
    * - Parameter
      - Comments
 
-   * - description, _description
+   * - **description**, **_description**
 
        `string`
      - Description of the family.
 
        User information to understand the usefulness of the family.
 
-   * - help, _help
+       .. seealso:: tutorial with a real world sample :ref:`description parameter <tutorial/family>`
+
+   * - **help**, **_help**
 
        `string`
      - Additional help associated with the family.
 
        .. seealso:: tutorial with a real world sample :ref:`help parameter <tutorial/examples>` (the tutorial focuses on variable, but the principle is the same for a family)
 
-   * - mode, _mode
+   * - **mode**, **_mode**
 
        `string`
      - Family mode.
 
-       The default mode of a family is the smallest mode of the parent families, child variables, or child families that are contained in that family.
+       The mode is a way of classifying the importance, the level of expertise required, or the access rights to a family.
 
-       This mode also allows you to define the default mode for variables or families included in this family.
+       This parameter allows you to define the family mode, and also the default mode for variables or families included in this family.
+
+       .. attention:: Mode is not configured by default. You have to define mode level before use this parameter.
+
+       **Default value**: The default mode of a family is the smallest mode of the parent families, child variables, or child families that are contained in that family.
 
        .. seealso:: tutorial with a real world sample :ref:`mode parameter <tutorial/mode>` (the tutorial focuses on variable, but the principle is the same for a family)
 
-   * - type, _type
+   * - **type**, **_type**
 
        `string`
-
      - possible values:
 
        - `family` (**default value**)
        - `dynamic`
        - `leadership`
 
-   * - hidden, _hidden
+   * - **hidden**, **_hidden**
 
-       `boolean` or `calculation`
+       `boolean` or :term:`calculation`
      - Invisible family.
 
-       Allows you to hide a family as well as the variables or families included in this family.
+       Enables us to *hide* a family as well as the variables or families included in this family.
 
        This means that the family will no longer be visible in `read-write` mode, but only for calculations or in `read-only` mode.
 
-       The default value is `false`.
+       **Default value**: `false`
 
        .. seealso:: tutorial with a real world sample :ref:`hidden parameter <tutorial/properties>`
 
-   * - disabled, _disabled
+   * - **disabled**, **_disabled**
-
-       `boolean` or `calculation`
 
+       `boolean` or :term:`calculation`
      - Disabled family.
 
-       Allows you to deactivate a family as well as the variables or families included in this family.
+       Allows us to *deactivate* a family as well as the variables or families included in this family.
 
        This means that the family will no longer be visible to the user but also to a :term:`calculation`.
 
-       The default value is `false`.
+       **Default value**: `false`
 
        .. seealso:: tutorial with a real world sample :ref:`disabled parameter <tutorial/properties>`
 
-   * - dynamic, _dynamic
+   * - **dynamic**, **_dynamic**
-
-       `calculation` or a list of `calculation` or `string`
 
+       :term:`calculation` or a list of :term:`calculation` or `string`
      - Dynamic identifiers.
 
-       .. important:: this parameter is only available for dynamically built family
+       .. important:: This parameter is only available for dynamically built family. See the explanations about this below.
+
+   * - **redefine**
+
+       `boolean`
+     - It is possible to define a family in one :term:`structure file` and change its behavior in a second :term:`structure file`. In this case you must explicitly redefine the family.
+
+       **Default value**: `false`
+
+   * - **exists**
+
+       `boolean`
+     - This parameter does two things:
+
+         - creates a family if it does not exist in another :term:`structure file` (otherwise do nothing), in this case the value of the parameter must be `true`
+         - in conjunction with the `redefine` parameter set to `true`, only modifies the behavior if it is pre-existing, in which case the parameter's value must be `false`.
+
+       **Default value**: `null`
+
 
 .. note::
 

docs/index.rst

@@ -49,7 +49,7 @@ Rougail
 
 .. toctree::
    :titlesonly:
-   :caption: The variables
+   :caption: The options
 
    variable
    family

docs/tags.rst

@@ -1,17 +1,6 @@
 The variable tags
 ==================
 
-A tag allows you to specialize a variable.
-
-A tag can have several functions:
-
-- Additional information in the documentation
-- Variable exclusion
-- Variable selection
-- ...
-
-Tags are only available for variable.
-
 Here is an example:
 
 .. code-block:: yaml

docs/variable.rst

@@ -42,7 +42,7 @@ Variable's types
 
 .. type-along:: type inference
 
-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.
+If the `type` parameter is not set, Rougail infers a `string` type for the `proxy_mode` configuration option variable type as defined in the structure file.
 
 .. type-along:: integer type
 
@@ -94,7 +94,7 @@ Shorthand declaration is a way to declare a variable in a single line. But you c
               default: true
 
 To create a variable, just add a key with it's name and default value as value.
-Be careful not to declare any other attributes.
+Be careful not to declare any other parameters.
 
 To declare a multi variable just add a list as default value.
 
@@ -117,6 +117,9 @@ If you add a comment in the same line of the name, this comment will be used has
 Parameters
 -------------
 
+
+
+
 .. list-table::
    :widths: 15 45
    :header-rows: 1
@@ -124,24 +127,125 @@ Parameters
    * - Parameter
      - Comments
 
+   * - **description**
+
+       `string`
+     - Description of the variable.
+
+       User information to understand the usefulness of the variable.
+
+       .. seealso:: tutorial with a real world sample :ref:`description parameter <tutorial/preliminary>`
+
    * - **help**
 
        `string`
      - Additional help associated with the variable.
 
-   * - **default**
+       .. seealso:: tutorial with a real world sample :ref:`help parameter <tutorial/examples>`
-     - Default value(s) of the variable.
 
-       This value is typed, you must correctly fill out the YAML file to avoid defining a value with an incorrect type. For example, a `integer` must be a digit type, a multiple variable must be a `list` type, ...
+   * - **mode**
 
-       For a non :term:`leading` multiple variable, the first value defined in the list will also be the default value proposed if a new value is added to this variable.
+       `string`
+     - Variable's mode.
+
+       The mode is a way of classifying the importance, the level of expertise required, or the access rights to a variable.
+
+       This parameter allows you to define the variable mode.
+
+       .. attention:: Mode is not configured by default. You have to define mode level before use this parameter.
+
+       **Default value**: The `default` mode of a variable is the mode of the parent family, but there is special cases:
+
+       - a variable with an automatically modified value or an automatic read-only variable is by default in the smaller mode
+       - if the variable is not in a family, the variable will have a medium mode by default
+       - a :term:`mandatory` variable without default value (calculate or not) will have the smaller mode
+
+       .. seealso:: tutorial with a real world sample :ref:`mode parameter <tutorial/mode>`
+
+   * - **tags**
+
+       `list of strings`
+     - A tag allows you to specialize a variable.
+
+       A tag can have several functions:
+
+       - Additional information in the documentation
+       - Variable exclusion
+       - Variable selection
+       - and so on
+
+   * - **examples**
+
+       `list`
+     - List of examples to illustrate possible values for a variable
+
+       .. seealso:: tutorial with a real world sample :ref:`examples parameter <tutorial/examples>`
+
+   * - **test**
+
+       `list`
+     - The `test` parameter is a special parameter that allows :term:`structure file` designers to influence a test robot by specifying useful values to test.
+
+       Concretely, the content of this parameter is recorded in the `information` parameter of the corresponding `Tiramisu` option object.
+
+   * - **type**
+
+       `string`
+     - Type of the variable.
+
+       See the list of available type below.
+
+       .. seealso:: tutorial with a real world sample :ref:`type parameter <tutorial/types>`
+
+   * - **params**
+
+       `object`
+     - Parameters to adjust type validation of the variable.
+
+       See the list of available parameters for each type below.
+
+       .. seealso:: tutorial with a real world sample :ref:`params parameter <tutorial/types>`
+
+   * - **multi**
+
+       `boolean`
+     - The value of the variable is a list.
+
+       **Default value**: mostly `false, but there is special cases:
+
+       - the default value is a list
+       - a variable with a variable :term:`multiple <multi>` has default value
+
+       It possible to adjust multi parameters with **params**:
+
+       - multi_length: number of expected values for a multiple variable
+       - multi_min_length: maximum number of expected values for a multiple variable
+       - multi_max_length: minimum number of expected values for a minimum variable
+
+       .. seealso:: tutorial with a real world sample :ref:`multi parameter <tutorial/multiple>`
 
    * - **validators**
 
        `list`
      - Value validators.
 
-       Jinja template list. The value of the variable will be considered invalid if the template has a return value.
+       The value of the variable will be considered invalid if the Jinja template return an error.
+
+       .. seealso:: tutorial with a real world sample :ref:`validators parameter <tutorial/validators>`
+
+   * - **default**
+     - Default value(s) of the variable.
+
+       This value is typed, you must correctly fill out the YAML file to avoid defining a value with an incorrect type. For example, a `integer` must be a digit type, a :term:`multiple <multi>` variable must be a `list` type, ...
+
+       For a non :term:`leading` :term:`multiple <multi>` variable, the first value defined in the list will also be the default value proposed if a new value is added to this variable.
+
+       .. seealso:: tutorial with a real world sample :ref:`default parameter <tutorial/preliminary>`
+
+   * - **secret_manager**
+     - The variable use a secret manager to get value
+       .. FIXME:: document it
+
    * - **auto_save**
 
        `boolean`
@@ -153,39 +257,43 @@ Parameters
 
        These variables are usually :term:`required` variables. In fact, these variables are only automatically modified if they have a value.
 
-       A :term:`leader` or :term:`follower` variable cannot have the `auto_save` property.
-
-       **Default value**: `false`
-   * - **mode**
-
-       `string`
-     - Variable's mode.
-
-       **Default value**: The `default` mode of a variable is the mode of the parent family.
-
-       Special cases :
-
-       - a variable with an automatically modified value or an automatic read-only variable is by default in `basic` mode
-       - if the variable is not in a family, the variable will have a `standard` mode by default
-       - a :term:`mandatory` variable without default value (calculate or not) will have a `basic` mode
-   * - **multi**
-
-       `boolean`
-     - The value of the variable is a list.
-
        **Default value**: `false`
 
-       **Parameters**:
+       .. seealso:: tutorial with a real world sample :ref:`auto_save parameter <tutorial/autosave>`
+
+   * - **mandatory**
+
+       `boolean` or :term:`calculation`
+     - Mandatory variable.
+
+       Variable whose value is `required`.
+
+       For a :term:`multiple <multi>` variable, this means that the list shall not be empty (means `null` (`None`) or empty list for a i:term:`multiple <multi>`).
+
+       **Default value**: `true`
+
+       .. seealso:: tutorial with a real world sample :ref:`mandatory parameter <tutorial/nullable>`
+
+   * - **empty**
+
+       `boolean` or :term:`calculation`
+     - The value `null` (`None`) is not allowed in :term:`multiple <multi>` variable.
+
+       The `mandatory` control only if the length :term:`multiple <multi>` variable is not 0. But the `null` value is not allowed. With empty parameter we can allowed it.
+
+       If `null` is an appropriate value, set empty: false.
+
+       **Default value**: `true`
 
-       - multi_length: number of expected values for a multiple variable
-       - multi_min_length: maximum number of expected values for a multiple variable
-       - multi_max_length: minimum number of expected values for a minimum variable
    * - **unique**
 
        `boolean`
-     - 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.
+     - The :term:`multiple <multi>` 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**
 
        `boolean` or :term:`calculation`
@@ -198,47 +306,52 @@ Parameters
        When a variable is made invisible, the user will not be able to modify its value; if he has already succeeded in modifying it, this value will not be taken into account.
 
        **Default value**: `false`
+
+       .. seealso:: tutorial with a real world sample :ref:`hidden parameter <tutorial/properties>` (the tutorial focuses on family, but the principle is the same for a variable)
+
    * - **disabled**
 
        `boolean` or :term:`calculation`
      - Disabled variable.
 
-       Allows us to deactivate a variable.
+       Allows us to *deactivate* a variable.
 
        This means that the variable will no longer be visible to the user but also to a :term:`calculation`.
 
        **Default value**: `false`.
-   * - **mandatory**
+
+       **Default value**: `false`
+
+       .. seealso:: tutorial with a real world sample :ref:`disabled parameter <tutorial/properties>` (the tutorial focuses on family, but the principle is the same for a variable)
+
+   * - **frozen**
 
        `boolean` or :term:`calculation`
-     - Mandatory variable.
+     - Read only variable.
 
-       Variable whose value is `required`.
+       Enables us to have an immutable variable.
+
+       This means that the variable will be visible but user will not allowed to change the value.
+
+       **Default value**: `false`
 
-       For a multiple variable, this means that the list shall not be empty.
 
-       **Default value**: `true`
    * - **redefine**
 
        `boolean`
      - It is possible to define a variable in one :term:`structure file` and change its behavior in a second :term:`structure file`. In this case you must explicitly redefine the variable.
 
        **Default value**: `false`
+
    * - **exists**
 
        `boolean`
-     - This attribute does two things:
+     - This parameter does two things:
 
-         - creates a variable if it does not exist in another :term:`structure file` (otherwise do nothing), in this case the value of the attribute must be `true`
+         - creates a variable if it does not exist in another :term:`structure file` (otherwise do nothing), in this case the value of the parameter must be `true`
-         - in conjunction with the `redefine` attribute set to `true`, only modifies the behavior if it is pre-existing, in which case the attribute's value must be `false`.
+         - in conjunction with the `redefine` parameter set to `true`, only modifies the behavior if it is pre-existing, in which case the parameter's value must be `false`.
 
        **Default value**: `null`
-   * - **test**
-
-       `list`
-     - The `test` attribute is a special attribute that allows :term:`structure file` designers to influence a test robot by specifying useful values to test.
-
-       Concretely, the content of this attribute is recorded in the `information` attribute of the corresponding `Tiramisu` option object.
 
 Variables type list
 --------------------