doc(variable): adjust parameters
This commit is contained in:
parent
4756e84d2e
commit
c0308145d5
4 changed files with 202 additions and 79 deletions
|
|
@ -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
|
||||
|
||||
`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 <tutorial/properties>`
|
||||
|
||||
* - 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::
|
||||
|
||||
|
|
|
|||
|
|
@ -49,7 +49,7 @@ Rougail
|
|||
|
||||
.. toctree::
|
||||
:titlesonly:
|
||||
:caption: The variables
|
||||
:caption: The options
|
||||
|
||||
variable
|
||||
family
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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**
|
||||
- Default value(s) of the variable.
|
||||
.. seealso:: tutorial with a real world sample :ref:`help parameter <tutorial/examples>`
|
||||
|
||||
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`
|
||||
- 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
|
||||
--------------------
|
||||
|
|
|
|||
Loading…
Reference in a new issue