diff --git a/docs/dictionary.rst b/docs/dictionary.rst index e8f483295..8471b8216 100644 --- a/docs/dictionary.rst +++ b/docs/dictionary.rst @@ -21,7 +21,7 @@ It is also possible to :term:`redefine` elements to change the behavior of a fam The default namespace ------------------------- -The families and variables contained in these dictionaries are ordered, by default, in the `rougail` namespace. It is possible to change the name of this namespace :doc:`with the `variable_namespace` parameter of the configuration `. +The families and variables contained in these dictionaries are ordered, by default, in the `rougail` namespace. It is possible to change the name of this namespace with the :term:`variable namespace ` parameter of the :doc:`configuration `. This namespace is a bit special, it can access variables in another namespace. diff --git a/docs/family.rst b/docs/family.rst index 964a4006e..4c5fdefe0 100644 --- a/docs/family.rst +++ b/docs/family.rst @@ -1,19 +1,28 @@ -A family -============ +The families +============= Synopsis --------- -A family is a container of variables and subfamily. +.. glossary:: + + family + families + + A family of variables 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. -Name -------------- +Naming conventions +------------------------ -It is with this name that we will be able to interact with the family. +It is with its name that we will be able to interact with the family. -It's best to follow the :ref:`convention on variable names`. +.. seealso:: + + Have a look at the :ref:`convention on variable names`. Shorthand declaration ---------------------------- @@ -35,7 +44,7 @@ If you add comment in same line of name, this comment is use as description: Parameters --------------- -.. FIXME: faire une page sur la "convention on variable names" +.. todo:: faire une page sur la "convention on variable names" .. list-table:: :widths: 15 45 diff --git a/docs/gettingstarted.rst b/docs/gettingstarted.rst index 2f9ef20cc..6349be04b 100644 --- a/docs/gettingstarted.rst +++ b/docs/gettingstarted.rst @@ -4,17 +4,14 @@ Getting started What is a consistency handling system ? ------------------------------------------------ -.. questions:: +.. questions:: Question "OK, I have understood that the Rougail stuff enables me to take advantage of :xref:`tiramisu`. - But what is all this for? - What is exactly a consistency handling system? - And again, what is this :xref:`tiramisu` library used for?" - *Answer*: Well, now we explain what this :xref:`tiramisu` library is, and how we are using it. + **Answer**: Well, now we explain what this :xref:`tiramisu` library is, and how we are using it. .. glossary:: @@ -30,9 +27,7 @@ What is a consistency handling system ? Here is the :xref:`tiramisu library`. In the Rougail scope, we call it :term:`variable`\ s and :term:`families`. -In Rougail, the families and variables are located in the :term:`structure files `. - -And this is what we are going to explain in this page. +In Rougail, the families and variables are located in the :term:`structure files ` (the term "dictionary" is also used as a synonym). The structure files --------------------- @@ -43,31 +38,27 @@ The structure files dictionary dictionaries - A dictionary in the Rougail meaning is a YAML file that describes variables + A dictionary or a a structure file in the Rougail meaning is a YAML file that describes variables and their dependencies / consistencies. There can be a lot of dictionary files located in many different folders. Rougail reads all the dictionaries and loads them into a single object that handles the variables consistency. - A dictionary file is a structure file, we call a dictionary a structure file. - .. image:: images/schema.png The main advantage is that declaring variables and writing consistency is as simple as writing YAML. With Rougail it is not necessary to write :term:`Tiramisu` code any more. It simplifies a lot of things. -And rather than writing :term:`Tiramisu` code, we can declare variables and describe the relationships between variables in a declarative mode (that is, in a YAML file). +And rather than writing :term:`Tiramisu` code, we can declare variables and describe the relationships between variables in a declarative style (that is, in a YAML file). -Once the structure files are loaded by Rougail, we find all the power of the :term:`Tiramisu` configuration management tool. +Once the structure files are loaded by Rougail, the Tiramisu configuration management tool can check the consistency of the variables between them. The YAML structure files format ------------------------------------ -Before getting started with Rougail we need to learn the specifics of the YAML dictionaries file format (as well as some templating concepts). - -.. todo:: parler de jinja https://jinja.palletsprojects.com +We need to learn first the specifics of the YAML dictionaries file format in Rougail, as well as some templating concepts. Here is an empty rougail dictionary YAML file @@ -106,7 +97,6 @@ The variables Here is a :term:`structure file ` example with a variable into it: .. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_010/firefox/00-proxy.yml - :linenos: :language: yaml :caption: A rougail dictionnary file with a variable named `proxy_mode`. It's the Rougail YAML dictionary format. :name: RougailDictionaryFirstVariable @@ -115,15 +105,12 @@ Here is a :term:`structure file ` example with a variable into it: --- proxy_mode: -:download:`source file ` - Here we declare a **variable** named `proxy_mode` without a default value. A variable can be defined with no default value at all. Here is the same variable with a description label: .. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_011/firefox/00-proxy.yml - :linenos: :language: yaml :caption: A rougail dictionnary file with a variable named `proxy_mode`, with a description. :name: RougailDictionaryFirstVariableDescription @@ -136,7 +123,6 @@ Here is the same variable with a description label: The same with a default value: .. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_012/firefox/00-proxy.yml - :linenos: :language: yaml :caption: A rougail dictionnary file with a variable named `proxy_mode`, with a default value. :name: RougailDictionaryFirstVariableDefault @@ -149,108 +135,15 @@ The same with a default value: variable - A variable is a declaration unit that represents a business domain metaphor, + A :term:`variable` is a declaration unit that represents a business domain metaphor, the most common example is that a variable that represents a configuration option in a application, but a variable represents something more that a configuration option. It provides a business domain specific representation unit. -.. todo:: définir une variable avec une description, un type, l'inférence de type, - les notations condensées, - une family sans variable doit avoir un type: family, - -.. note:: Dictionaries can just define a list of variables, but we will see that - we can specify a lot more. We can define variables **and** their relations, - **and** the relations between them. - -In the next step, we will explain through a tutorial how to construct a list of variables. - Families of variables -------------------------- -.. glossary:: +family - family - families - - A family of variables 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. - -A "hello world" with Rougail ------------------------------- - -We're gonna make the simplest possible example. - -.. prerequisites:: Prerequisites - - We assume that Rougail's library is installed on your computer (or in a virtual environment). - -.. exercise:: Hello world's workshop - - Here is the tree structure we want to have:: - - workplace - ├── dict -    │   ├── hello.yml -    └── hello.py - -- Let's make a :file:`workplace` directory, with a :file:`dict` subfolder. -- First, we need a :term:`dictionary`, so let's make the :file:`hello.yml` file - which is located in the :file:`dict` subfolder, with the following content: - -.. code-block:: yaml - :caption: The `hello.yaml` file - - --- - version: '1.1' - hello: - default: world - -.. todo:: mettre un appel à la CLI pour lancer le truc - -We launch the script: - -.. code-block:: bash - - python hello.py - -And we obtain the following result: - -.. code-block:: python - - {'rougail.hello': 'world'} - -**Congratulations ! You have successfully completed your first Rougail script.** - -A "Hello, " sample with a family ------------------------------------------- - -Let's continuing on our "Hello world" theme and add a :term:`family` container. - -.. code-block:: yaml - :caption: the :file:`hello.yml` file - :linenos: - - --- - version: '1.1' - world: - description: Hello world family container - name: - description: Somebody to say hello - default: rougail - -Here, we have a family named `world`. -This family contains a variable named `name` - -Again, let's validate this YAML file against Rougail's API: - -.. code-block:: bash - - python hello.py - -We then have the output: - -.. code-block:: python - - {'rougail.world.name': 'rougail'} + A :term:`family` is simply a container of variables and subfamily. diff --git a/docs/index.rst b/docs/index.rst index 26e8aef2f..301c74e3e 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -10,11 +10,32 @@ Rougail .. todolist:: + +.. todo:: définir les termes suivants + + family.rst:25: WARNING: label non défini: 'convention on variable names' + /family.rst:114: WARNING: term not in glossary: 'calculation' + /variable.rst:39: WARNING: label non défini: 'convention on variable names' + /variable.rst:83: WARNING: term not in glossary: 'leading' + /variable.rst:100: WARNING: term not in glossary: 'required' + /variable.rst:102: WARNING: term not in glossary: 'leader' + /variable.rst:102: WARNING: term not in glossary: 'follower' + /variable.rst:126: WARNING: term not in glossary: 'multiple' + /variable.rst:126: WARNING: term not in glossary: 'multiple' + /variable.rst:131: WARNING: term not in glossary: 'calculation' + /variable.rst:143: WARNING: term not in glossary: 'calculation' + /variable.rst:148: WARNING: term not in glossary: 'calculation' + /variable.rst:153: WARNING: term not in glossary: 'calculation' + /dictionary.rst:9: WARNING: term not in glossary: 'templates' + /dictionary.rst:19: WARNING: term not in glossary: 'redefine' + /dictionary.rst:24: WARNING: term not in glossary: 'variable_namespace' + + .. image:: images/logo.png - is a `delicious cooked dish `_ from the Mauritius and Reunion Islands, -- it is also a `Python3 `_ library which enables us to conveniently load application :term:`variable`\ s in a simple `YAML `_ format in such a way that the end user consumer can handle them consistently (that is, against an user-defined consistency). +- it is also a `Python `_ library which enables us to conveniently load application :term:`variable`\ s in a simple `YAML `_ format in such a way that the end user consumer can handle them consistently (that is, against an user-defined consistency). In other words, using Rougail in your application or your python libraries can tansform end user consumer defined consistency rules into highly consistent business objects. diff --git a/docs/tutorial/index.rst b/docs/tutorial/index.rst index 26254a89a..46a5b758f 100644 --- a/docs/tutorial/index.rst +++ b/docs/tutorial/index.rst @@ -1,29 +1,35 @@ Tutorial with a real world sample ===================================== -Here's a quite well supplied tutorial, we're gonna start with a use case that comes from the real world. +Here is a fairly complete tutorial, this is a use case that comes from the real world. +At the end of the tutorial you will have a good understanding of rougail. .. objectives:: Configuring (the setting of) your favorite web browser This tutorial will show you an example of Rougail use based on the - "how to set a proxy" in the `Mozilla Firefox `_ browser + *how to set a proxy* in the `Mozilla Firefox `_ browser use case. -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: +More precisely, this tutorial aims at reproducing :term:`variable`\ s behind this Mozilla Firefox settings page: .. image:: images/firefox.png -.. note:: We are not coding a firefox plugin here. +We'll call the variables **configuration options** since that's what the variables represent in this case. + +.. attention:: 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 option configuration variables ----------------------------------------------------------- -Let's dive into this configuration validation use case. -The values entered by the user that have to be validated. +Let's dive into this **configuration options validation** use case. +The values entered by the user have to be -At first glance we have a selection of five options configuration values that we need to fill in: +- validated +- consitent. + +At first glance we can see that we have a selection of five configuration options values that we need to fill in (they are highlighted here in this screenshot): .. image:: images/firefox_01.png diff --git a/docs/tutorial/preliminary.rst b/docs/tutorial/preliminary.rst index df24abbb3..60ed1c6ce 100644 --- a/docs/tutorial/preliminary.rst +++ b/docs/tutorial/preliminary.rst @@ -9,26 +9,29 @@ Preliminaries - define a Rougail format version - define a Rougail :term:`variable` and set its :term:`value` -.. type-along:: Reminders +.. type-along:: Basics - We already learned in other workshops how to: +Dictionary +------------- - - define a Rougail :term:`structure description file ` +Define a Rougail :term:`structure description file ` - :ref:`Here is an empty Rougail dictionnary ` +https://forge.cloud.silique.fr/stove/rougail-tutorials/src/commit/v1.1_000/firefox/00-proxy.yml - - define a variable and its default value - :ref:`Here is a first Rougail variable in a Rougail dictionnary ` +Here is an empty Rougail dictionnary ` - - define a variable with a description +- define a variable and its default value - :ref:`Here is a Rougail variable with a description ` + :ref:`Here is a first Rougail variable in a Rougail dictionnary ` - - define a variable with a description and a default value +- define a variable with a description - :ref:`Here is a Rougail variable with a default value ` + :ref:`Here is a Rougail variable with a description ` +- define a variable with a description and a default value + + :ref:`Here is a Rougail variable with a default value ` The integrator role ---------------------- @@ -121,7 +124,7 @@ Rougail waits for the `proxy_mode` configuration option's value to be set. A variable is mandatory when a value is required, that is, `None` is not an option. -Typing a variable +Variable's type ----------------- 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. diff --git a/docs/variable.rst b/docs/variable.rst index 59f9b9f6a..3fa3b9c1b 100644 --- a/docs/variable.rst +++ b/docs/variable.rst @@ -13,22 +13,30 @@ Synopsis value - A variable can have a default value, that is a option configuration setting in the :term:`dictionary` structure, - or no value at all, then the value needs to be define by the :term:`operator`. + A value is a variable's setting. + Variable can have a default value, that is a setting defined in the :term:`dictionary` structure, + or no value at all, then the value needs to be define later by the :term:`operator`. .. discussion:: Discussion - This definition makes a heavy use of data typing. - Indeed, depending on the type system definition of the constistency handling system used, variables may only be able to store a specified data type. - OK, variables are the containers for storing the values. It has something to do with typing. - But this is not just about typing. + The variable is, by definition, strongly typed. + Rougail uses static type definition and even type inference. + Indeed, the constistency handling system heavyly relies on the type system definition. + Variables may only be able to store a specified data type. + OK, variables are the containers for storing the values. It has something to do with typing. + + But consitency handling system is is not just about strong typing. It is more than that. -Name +Names ------ -Variable's associated symbolic name. +Variable name -It's best to follow the :ref:`convention on variable names`. + Variable's associated symbolic name. + +.. seealso:: + + Have a look at the :ref:`convention on variable naming link `. Shorthand declaration ----------------------------