diff --git a/docs/family.rst b/docs/family.rst index e2601c02d..8b9ef2801 100644 --- a/docs/family.rst +++ b/docs/family.rst @@ -9,43 +9,60 @@ Synopsis family subfamily - A family (or a subnfamiliy) of variables is simply a collection of variables that refer to + A family (or a subfamily) is simply a collection of variables that refer to the same business model category. It's just a variables container. Think of it as a container as well as a namespace. .. attention:: A family without a subfamily or subvariable will be automatically deleted. -Naming conventions ------------------------- +Naming +--------- It is with its name that we will be able to interact with the family. .. seealso:: - Have a look at the :ref:`convention on variable names`. + Have a look at the :ref:`family naming convention ` Shorthand declaration ---------------------------- -Shorthand declaration is a way to declare a family in a single line. But you can only define family name and description. +Shorthand declaration is a way to declare a family in a single line. -To create a family, just add a key with it's name and variables as values. Attention, do not declare any other attributs. +To create a family, just add a key with it's name and variables as values. -By default, the description of the variable is the family name. -If you add comment in same line of name, this comment is use as description: +Here is a simple example: .. code-block:: yaml + %YAML 1.2 --- - version: '1.1' - my_family: # This is a great family + version: 1.1 + my_family: + variable: + ... + +By default, the description of the variable is the family name. +It's a best practice to description a family. Just add comment in same line of name, this comment is use as description. + +.. code-block:: yaml + + %YAML 1.2 + --- + version: 1.1 + my_family: # This is a great family + + variable: + ... + +But in shorthand notation, you can only define family name and description. + +.. attention:: Any other parameters will be considered as a variable. Do not use shorthand in this case. Parameters --------------- -.. todo:: faire une page sur la "convention on variable names" - .. list-table:: :widths: 15 45 :header-rows: 1 @@ -53,18 +70,6 @@ Parameters * - Parameter - Comments - * - type, _type - - `string` - - - possile values: - - - `family` (**default value**) - - `leadership` - - `dynamic` - - .. note:: If a subfamily or a subvariable already has the name `"type"`, it is possible to use the `"_type"` attribute. - * - description, _description `string` @@ -72,14 +77,12 @@ Parameters User information to understand the usefulness of the family. - ..note:: If a subfamily or subvariable already has the name "description" it is possible to use the "_description" attribute. - * - help, _help `string` - Additional help associated with the family. - .. note:: If a subfamily or a subvariable already has the name "help" it is possible to use the "_help" attribute. + .. 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 @@ -90,22 +93,34 @@ Parameters This mode also allows you to define the default mode for variables or families included in this family. - .. note:: If a subfamily or a subvariable already has the name "mode" it is possible to add the "_mode" attribute. + .. 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 + + `string` + + - possible values: + + - `family` (**default value**) + - `dynamic` + - `leadership` * - hidden, _hidden - `string` + `boolean` or `calculation` - Invisible family. Allows you 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. - .. note:: If a subfamily or a subvariable already has the name "hidden" it is possible to add the "_hidden" attribute. + The default value is `false`. + + .. seealso:: tutorial with a real world sample :ref:`hidden parameter ` * - disabled, _disabled - `string` + `boolean` or `calculation` - Disabled family. @@ -113,159 +128,137 @@ Parameters This means that the family will no longer be visible to the user but also to a :term:`calculation`. - .. note:: If a subfamily or a subvariable already has the name "disabled" it is possible to use the "_disabled" attribute. + The default value is `false`. -Dynamically created family ------------------------------ + .. seealso:: tutorial with a real world sample :ref:`disabled parameter ` -To create a family dynamically, you must create a fictitious family linked to a calculation. -The family name will actually be the prefix of the new name. Alternativly you can specify the suffix in the name, ie `my_{{ suffix }}_name`. -The suffix will come from the calculation. + * - dynamic, _dynamic -Obviously if the result of calculation were to evolve, new dynamic families will appear or disappear. + `calculation` or a list of `calculation` or `string` -Leader or follower variable ------------------------------ + - Dynamic identifiers. -A leader family has a typical attribute of “leadership”. The type is required. + .. important:: this parameter is only available for dynamically built family -A leader family ----------------- +.. note:: -The leader and follower variables are placed in a leader family. + If a subfamily or a subvariable already has the name of a parameter it is possible to use the "_" name. + You can have a look at the tutorial with a real world sample :ref:`of parameter with "_" `. -A leader family cannot contain other families. +A family +--------- -The default mode of the leader family is the mode of the leader variable. - -Leader variable ----------------- - -A leader variable is a variable that will guide the length of other variables (called follower variables). - -A leader variable is a :doc:`variable` that must have the `multiple` type. - -A leader variable may be mandatory. - -The default mode corresponds to the smallest mode defined for the follower variables. - -Follower variable --------------------- - -A follower variable is a variable whose length is not determined by itself, but is identical to that of the leader variable on which it depends. - -A follower variable is a variable placed just behind a leader variable or another follower variable. - -The order in which the tracking variables are defined is important. - -This variable can be of multiple type. In this case, for a determined index of the leading variable, it is possible to put several values to the same variable. - -A follower variable may be required. This means that when a leader variable is entered, the follower variable must also be a value at the index considered. If no value is defined for the leader variable, no value is specified for the follower variable. - -The default mode of a follower variable corresponds to the mode of the leader variable. - -If a leader variable is hidden or disabled, the follower variables will be hidden or disabled as well. - -Examples ----------- - -Simple family: +Here is a simple example: .. code-block:: yaml + %YAML 1.2 --- - version: '1.1' + version: 1.1 my_family: - type: family description: This is a great family - help: This is the help of a great family - mode: expert + help: This family is great because we have great variables inside -Dynamically created family ----------------------------- + variable: + ... + +.. seealso:: + + You can have a look at the tutorial with a real world sample: + + - :ref:`family ` + - :ref:`help parameter ` (the tutorial focuses on variable, but the principle is the same for a family) + +A dynamically built family +----------------------------- + +To create a family dynamically, you must create a fictitious family linked to a list of uniq identifiers. +This list could be hard coded or resulting from a calculation + +In this case if the result of calculation were to evolve, new dynamic families will appear or disappear. + +The name of this family is particular. You have to add `{{ identifier }}` string inside. It will be replace by each identifiers. + +Here is an simple example: .. code-block:: yaml + %YAML 1.2 --- - version: '1.1' - varname: - multi: true - default: - - val1 - - val2 - my_dyn_family_: - type: dynamic + version: 1.1 + + my_{{ identifier }}_family: + description: 'A family for {{ identifier }}' dynamic: - type: variable - variable: rougail.varname - description: 'Describe' - my_dyn_var: - type: string - description: 'Variable description' + - one thing + - another + + variable: + description: 'A variable for {{ identifier }}' + ... This will dynamically create two families: -- "rougail.my_dyn_family_val1" -- "rougail.my_dyn_family_val2" +- "my_one_thing_family" +- "my_another_family" -In the dynamic family "rougail.my_dyn_family_val1" we will find a variable "my_dyn_var". +.. seealso:: -Here is a second example: + You can have a look at the tutorial with a real world sample :ref:`dynamically built family ` + +Similar object sequence +------------------------- + +A family with `type` set to `leadership` is a sequence of similar object. + +Let's start the explanation with a concrete example: + +.. code-block:: yaml + + %YAML 1.2 + --- + version: 1.1 + + accounts: + description: All accounts + type: leadership + + login: + description: Account login + type: unix_user + + secret: + description: Account secret + type: secret + ... + +What is expected, it's something like: .. code-block:: yaml --- - version: '1.1' - varname: - multi: true - default: - - val1 - - val2 - my_dyn_{{ suffix }}_family: - type: dynamic - dynamic: - type: variable - variable: rougail.varname - description: 'Describe' - my_dyn_var: - type: string - description: 'Variable description' + accounts: + - login: foo + secret: 0hM%G0dW4a7ASecr3t + - login: bar + secret: NotGoodSecret -This will dynamically create two families: +It's what we call a sequence of similar object. -- "rougail.my_dyn_val1_family" -- "rougail.my_dyn_val2_family" +.. attention:: A sequence cannot contain other families. -In the dynamic family "rougail.my_dyn_val1_family" we will find a variable "my_dyn_var". +.. seealso:: -Leader or follower variable -------------------------------- + You can have a look at the tutorial with a real world sample :ref:`similar object sequence ` -Definition of leader and follower variables -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +A custom type family +---------------------- -Here is an example of defining a leading variable and two following variables: +In short, a custom type is nothing more than a kind of a template for a family. +Define a custom type family is much like defining families. -.. code-block:: yaml +This custom type family can be used as many times as desired and customized as you wish. - --- - version: '1.1' - family: - type: leadership - leader: - multi: true - follower1: - follower2: - multi: true +.. seealso:: -Adding a new follower variable -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -To add a new follower variable, in a new dictionary, simply define one or more new variables in the leader family: - -.. code-block:: yaml - - --- - version: '1.1' - family: - follower3: + You can have a look at the tutorial with a real world sample :ref:`family custom type ` diff --git a/docs/tutorial/examples.rst b/docs/tutorial/examples.rst index d7c063f84..2330cfb94 100644 --- a/docs/tutorial/examples.rst +++ b/docs/tutorial/examples.rst @@ -250,6 +250,8 @@ command-line utility when you type the command with the `--help` or `-h` option. A `help` helps to clarify any ambiguity about the variable’s purpose. It can be long and detailed. +We can set `help` attribute to a variable or to a family. + .. keypoints:: Key points - We have seen how to give examples, simply with the `examples` parameter diff --git a/docs/tutorial/family.rst b/docs/tutorial/family.rst index e93860581..3e44bae98 100644 --- a/docs/tutorial/family.rst +++ b/docs/tutorial/family.rst @@ -108,7 +108,7 @@ Or a sub family .. type-along:: For those who follow the tutorial with the help of the git repository Now you need to checkout the :tutorial:`v1.1_021 ` version:: - + git switch --detach v1.1_021 .. glossary:: @@ -152,7 +152,7 @@ Putting a variable inside of a family or a sub family .. type-along:: For those who follow the tutorial with the help of the git repository Now you need to checkout the :tutorial:`v1.1_022 ` version:: - + git switch --detach v1.1_022 We are going to put a variable inside of a family or a sub family @@ -215,7 +215,7 @@ Here is a user data file sample: :language: yaml :caption: A user file named :file:`config/03/config.yml` with a value set for the `address` variable :name: RougailAddresseVariableUserValue - + .. --- proxy_mode: Manual proxy configuration @@ -270,3 +270,7 @@ Let's recap about the user data. We can see in this Rougail CLI output that: - we have a :term:`family` named `manual` and a sub family named `http_proxy` - And we have now two variables: :confval:`proxy_mode` and :confval:`address`. + +.. seealso:: + + Full documentation about :ref:`family ` diff --git a/docs/tutorial/practice1.rst b/docs/tutorial/practice1.rst index 876ce9b14..a91900f43 100644 --- a/docs/tutorial/practice1.rst +++ b/docs/tutorial/practice1.rst @@ -53,8 +53,8 @@ What do we want to be implemented You need to think about: - - choose a file name that respect the :ref:`file naming and organizing convention ` - - define an appropriate variable name, have a look at our :ref:`file naming convention ` + - choose a file name that respect the :ref:`file naming and organizing convention ` + - define an appropriate variable name, have a look at our :ref:`variable naming convention ` - the Firefox description is in negative mode, which is not a good practice for us, we rewrite it in positive mode - the variable is a boolean with the default value `true` (the opposite of unchecked option) - the variable is available for all proxy mode choice by user, so disable it only when the `proxy mode` is "No proxy". @@ -98,8 +98,8 @@ What do we want to be implemented You need to think about: - - the choice of a file name that respect the :ref:`file naming and organizing convention ` - - in order to define an appropriate variable name, + - the choice of a file name that respect the :ref:`file naming and organizing convention ` + - define an appropriate variable name, have a look at our :ref:`variable naming convention ` - the `description` parameter will be the Firefox description, - the variable is a boolean with the default value `false` (unchecked option), - the variable is only available with the `"Manual proxy configuration"` proxy mode and when the proxy socks version is not v4. diff --git a/docs/tutorial/underscore_parameter.rst b/docs/tutorial/underscore_parameter.rst new file mode 100644 index 000000000..c35caecdb --- /dev/null +++ b/docs/tutorial/underscore_parameter.rst @@ -0,0 +1,64 @@ +A variable name that conflict with a defined family's attribute +============================================================================== + +.. objectives:: Objectives + + Have a good variable name is really important. + + We will learn how to create a variable name that conflict with a defineed attribute name. + +.. prerequisites:: Prerequisites + + - We assume that Rougail's library is :ref:`installed ` on your computer. + + - It is possible to retrieve the current state of the various Rougail files manipulated in this tutorial step + by checking out the corresponding tag of the `rougail-tutorials` git repository. + Each tag corresponds to a stage of progress in the tutorial. + Of course, you can also decide to copy/paste or download the tutorial files contents while following the tutorial steps. + + If you want to follow this tutorial with the help of the corresponding :tutorial:`rougail-tutorials git repository `, + this workshop page corresponds to the tag :tutorial:`v1.1_210 ` + in the repository. + + :: + + git clone https://forge.cloud.silique.fr/stove/rougail-tutorials.git + git switch --detach v1.1_210 + +.. type-along:: Let's recap how far we've come + +We have this leadership family in its structure definition file: + +.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_202/foxyproxy/00-foxyproxy.yml + :linenos: + :language: yaml + :caption: The `proxies` family with `leadership` type in the :file:`foxyproxy/00-foxyproxy.yml` structure file + +The variable "type" that conflit with the family attribute "type" +--------------------------------------------------------------------- + +Choice a good variable name is important. It's with this name that user will interact with here value. + +The user has to define the type of the new proxy. So instinctively the name of the variable will be `type`. + +But in the current family we have already the attribute `type` with the `leadership` value. +YAML do not permit to have two key with the same name. +Maybe we could choice an other variable name like `proxy_type` but the full path will be `proxies.proxy_type`. +Repeating the word proxy is not appropriate. + +So the best way it to rename the `type` attribute to `_type` + +Let's create a family named `manual` which obviously corresponds to the proxy's manual configuration choice. + +.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_210/foxyproxy/00-foxyproxy.yml + :language: yaml + :caption: The `proxies` family with `leadership` type and a variable with the name `type` in the :file:`foxyproxy/00-foxyproxy.yml` structure file + +Technically it's possible to put `_` in front of each attribute name, but it's still less readable. + +.. keypoints:: Let's review the key points + + **Keywords** + + - attributes could start by "_" character or not + - do not add `_` in front of all attributes name