diff --git a/docs/tutorial/index.rst b/docs/tutorial/index.rst index 11ebe4d9d..26254a89a 100644 --- a/docs/tutorial/index.rst +++ b/docs/tutorial/index.rst @@ -9,20 +9,19 @@ Here's a quite well supplied tutorial, we're gonna start with a use case that co "how to set a proxy" in the `Mozilla Firefox `_ browser use case. -More precisely, this tutorial aims at reproducing :term:`variable`\ s (that is, configuration options) behind this Mozilla Firefox settings page: +More precisely, this tutorial aims at reproducing :term:`variable`\ s (in this use case we will call them configuration options) behind this Mozilla Firefox settings page: .. image:: images/firefox.png -.. attention:: We are not coding a firefox plugin here. +.. note:: We are not coding a firefox plugin here. We are just going to handle some of the firefox configuration settings with Rougail. - -Presentation of the firefox configuration variables +Presentation of the firefox option configuration variables ----------------------------------------------------------- -Let's dive into the configuration validation use case, -that is the values entered by the user that have to be validated. +Let's dive into this configuration validation use case. +The values entered by the user that have to be validated. At first glance we have a selection of five options configuration values that we need to fill in: diff --git a/docs/tutorial/preliminary.rst b/docs/tutorial/preliminary.rst index c7fcfdbee..df24abbb3 100644 --- a/docs/tutorial/preliminary.rst +++ b/docs/tutorial/preliminary.rst @@ -86,14 +86,14 @@ So, if : .. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_010/firefox/00-proxy.yml :linenos: :language: yaml - :caption: The :file:`struct/config.yaml` rougail structure file, with no default value set. + :caption: The :file:`firefox/00-proxy.yaml` rougail structure file, with no default value set. :name: RougailDictionaryNoDefault .. --- proxy_mode: -In this situation there are no default value set. The rougail CLI will output an error : +Then the rougail CLI will output an error : .. code-block:: shell :caption: A rougail Command Line Utility call with the :file:`config/01/config.yaml` rougail dictionnary file @@ -111,16 +111,21 @@ In this situation there are no default value set. The rougail CLI will output an .. important:: Once defined, an option configuration :term:`value` is :term:`mandatory`. -Rougail waits for a value to be set, that's why. +Rougail waits for the `proxy_mode` configuration option's value to be set. .. seealso:: To go further, have a look at the :tiramisu:`mandatory option ` Tiramisu's definition. -Type inference +.. glossary:: + + mandatory + + A variable is mandatory when a value is required, that is, `None` is not an option. + +Typing a variable ----------------- -By default, rougail infers a `string` type for the `proxy_mode` configuration option variable type as defined -in the structure file. -. +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 operator sets an option value for example with the `number` type, like this: .. code-block:: yaml @@ -133,10 +138,10 @@ If the operator sets an option value for example with the `number` type, like th Then rougail will expect a `int` or a `float` as a value for the `example_var` variable. In our firefox use case, the real type of the `proxy_mode` variable is a `choice` type: -.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_013/config/05/config.yaml +.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_013/firefox/00-proxy.yml :linenos: :language: yaml - :caption: The :file:`config/05/config.yaml` rougail dictionnary file, with a default value set. + :caption: The :file:`firefox/00-proxy.yml` rougail dictionnary file, with a default value set. :name: RougailDictionaryChoiceTypeWitheDefault .. @@ -166,6 +171,33 @@ In our firefox use case, the real type of the `proxy_mode` variable is a `choice ┗━━ 📓 proxy_mode: No proxy +The `proxy_mode` variable here, implicitely requires a value. It is a :term:`mandatory` variable. + +It shall have a value, but what if the user *does not* specify any value? +There is a possibility of setting a default value, wich is set as `No proxy` by default. + +Container type +----------------- + +We say that the `proxy_mode` variable is *constrained* (by the `choice` type). + +We have the list of the possible (authorized) values: + +- `No proxy` +- `Auto-detect proxy settings for this network` +- `Use system proxy settings` +- `Manual proxy configuration` +- `Automatic proxy configuration URL` + +.. glossary:: + + choice type + + The `proxy_mode` setting is "choice" (`type: choice`) means that + there is a list of available values that can be selected. + +.. note:: Indeed, in the Firefox configuration, it is possible to define several configuration modes, + from no proxy at all (`no proxy`) to a kind of automatic configuration mode from a file (`set up proxy configuration from a file`). .. keypoints:: Key points progress @@ -178,6 +210,7 @@ In our firefox use case, the real type of the `proxy_mode` variable is a `choice - a variable's default value - the :term:`integrator` and :term:`operator` roles - a mandatory value + - a choice type To sum up, we have arrived at this point in writing the structure file: diff --git a/docs/tutorial/proxymode.rst b/docs/tutorial/proxymode.rst index 30f70bc4b..3737fd990 100644 --- a/docs/tutorial/proxymode.rst +++ b/docs/tutorial/proxymode.rst @@ -1,25 +1,35 @@ -Firefox tutorial: the `mode_proxy` variable ------------------------------------------------- - The `proxy` family -------------------- +==================== -Let's create our first :term:`dictionary`. -.. prerequisites:: Let's create a folder named `dict` and a dictionary file inside +.. objectives:: Objectives -We will put our dictionary files in this folder. + We will learn how to: -Then let's put our first dictionary file in this folder, named :file:`00-proxy.yml` + - create a :term:`family` + - gather variables into a family + - make a variable in a variable, which is a family too -.. code-block:: yaml - :caption: the :file:`00-proxy.yml` file + +.. type-along:: Reminders + + - As a prerequisite we have an idea of what a :term:`structure file description ` is. + - We have a :file:`firefox` folder and we are putting all the structure description files in it. + - We had at the :term:`structure description file ` + +A `manual` family +-------------------- + +.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_020/firefox/10-manual.yml :linenos: + :language: yaml + :caption: A family structure file description named `manual` in the :file:`firefox/10-manual.yml` file + :name: RougailFirstDictionary +.. --- - version: '1.1' - proxy: - description: Proxy configuration in order to have access to the internet + manual: + description: Manual proxy configuration type: family We can see that we have defined a :term:`family` here, and this family is *empty* @@ -27,67 +37,66 @@ We can see that we have defined a :term:`family` here, and this family is *empty .. admonition:: If a family is empty - We need to specify the :term:`family` type (line 5) here because if we don't, + We need to specify the :term:`family` type here because if we don't, the Rougail's type engine will infer it by default as a :term:`variable`. -It's because we don't have set any :term:`variable` inside. +It's because we don't have set any :term:`variable` inside. If we make a YAML block +(that is, if we indent), the Rougail's type inference engine will implicitely make it a family. - -.. note:: The variables will be created in several files for educational purposes. +.. note:: The variables, families, etc. will be created in several files for educational purposes. Obviously all the variables can be put in the same file. +A family inside a family +---------------------------- -The proxy's configuration type ----------------------------------- +Creating a family hierarchy is very easy, here is an example -In the Firefox configuration, it is possible to define several configuration modes, -from no proxy at all (`no proxy`) to a kind of automatic configuration mode from a file (`set up proxy configuration from a file`). +.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_021/firefox/10-manual.yml + :linenos: + :language: yaml + :caption: A rougail structure description file with a hierarchy. + :name: RougailFirstFamilyHierarchy + +.. + --- + manual: + description: Manual proxy configuration + type: family + + http_proxy: + description: HTTP Proxy + type: family + +Here the `http_proxy` family lives inside the `manual` family. + +Put a variable inside a family or a sub family +-------------------------------------------------- Let's create a variable in its family with a description and a default value. The type of this variable is a `choice` type: -.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_006/firefox/00-proxy.yml +.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_022/firefox/10-manual.yml :linenos: :language: yaml - :caption: A rougail dictionnary file with a choice variable named `proxy_mode`, with a default value and a description. - :name: RougailDictionaryFirstVariableChoiceType + :caption: An `address` variable in the `http_proxy` family + :name: RougailVariableInSubFamily -.. glossary:: +.. + --- + manual: + description: Manual proxy configuration + type: family - mandatory + http_proxy: + description: HTTP Proxy + type: family - A variable is mandatory when a value is required, that is, `None` is not an option. + address: + description: HTTP address -The `proxy_mode` variable here, implicitely requires a value. It is a mandatory variable. +.. keypoints:: Key points progress -It shall have a value, but what if the user *does not* specify any value? -There is a possibility of setting a default value, wich is set as `No proxy` by default. - -.. glossary:: - - choice type - - The `proxy_mode` setting is "choice" (`type: choice`) means that - there is a list of available values that can be selected. - -We say that the `proxy_mode` variable is *constrained* (by the `choice` type). - -We have the list of the possible (authorized) values: - -- `No proxy` -- `Auto-detect proxy settings for this network` -- `Use system proxy settings` -- `Manual proxy configuration` -- `Automatic proxy configuration URL` - -Now let's test our first two dictionaries: - ->>> from rougail import Rougail, RougailConfig ->>> from pprint import pprint ->>> RougailConfig['dictionaries_dir'] = ['dict'] ->>> rougail = Rougail() ->>> config = rougail.get_config() ->>> config.property.read_only() ->>> pprint(config.value.get(), sort_dicts=False) -{'rougail.proxy.proxy_mode': 'No proxy'} + **Keywords** + - :term:`family`, and sub families + - variables defined in a family