From c0308145d51674100a90d88af49112cdce3d3e9f Mon Sep 17 00:00:00 2001 From: Emmanuel Garette Date: Mon, 1 Jun 2026 08:55:35 +0200 Subject: [PATCH] doc(variable): adjust parameters --- docs/family.rst | 61 +++++++++----- docs/index.rst | 2 +- docs/tags.rst | 11 --- docs/variable.rst | 207 +++++++++++++++++++++++++++++++++++----------- 4 files changed, 202 insertions(+), 79 deletions(-) diff --git a/docs/family.rst b/docs/family.rst index 8b9ef2801..d0ef88f54 100644 --- a/docs/family.rst +++ b/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 ` + + * - **help**, **_help** `string` - Additional help associated with the family. .. seealso:: tutorial with a real world sample :ref:`help parameter ` (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 ` (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 ` - * - disabled, _disabled - - `boolean` or `calculation` + * - **disabled**, **_disabled** + `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 ` - * - dynamic, _dynamic - - `calculation` or a list of `calculation` or `string` + * - **dynamic**, **_dynamic** + :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:: diff --git a/docs/index.rst b/docs/index.rst index 03cc37d08..5cfff9d81 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -49,7 +49,7 @@ Rougail .. toctree:: :titlesonly: - :caption: The variables + :caption: The options variable family diff --git a/docs/tags.rst b/docs/tags.rst index e5cd7bc46..009d074d3 100644 --- a/docs/tags.rst +++ b/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 diff --git a/docs/variable.rst b/docs/variable.rst index 2db62e5bc..dc423a43f 100644 --- a/docs/variable.rst +++ b/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 ` + * - **help** `string` - Additional help associated with the variable. - * - **default** - - Default value(s) of the variable. + .. seealso:: tutorial with a real world sample :ref:`help parameter ` - 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 ` + + * - **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 ` + + * - **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 ` + + * - **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 ` + + * - **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 ` 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 ` * - **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 ` + + * - **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 ` variable must be a `list` type, ... + + For a non :term:`leading` :term:`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. + + .. seealso:: tutorial with a real world sample :ref:`default parameter ` + + * - **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 ` + + * - **mandatory** + + `boolean` or :term:`calculation` + - Mandatory variable. + + Variable whose value is `required`. + + For a :term:`multiple ` variable, this means that the list shall not be empty (means `null` (`None`) or empty list for a i:term:`multiple `). + + **Default value**: `true` + + .. seealso:: tutorial with a real world sample :ref:`mandatory parameter ` + + * - **empty** + + `boolean` or :term:`calculation` + - The value `null` (`None`) is not allowed in :term:`multiple ` variable. + + The `mandatory` control only if the length :term:`multiple ` 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 ` 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 ` 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. **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 ` (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 ` (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` - - 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`. + - 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` 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 --------------------