modifs
This commit is contained in:
gwen
parent
bf6120f95e
commit
98f788ee9b
7 changed files with 94 additions and 154 deletions
|
|
@ -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 <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 <variable_namespace>` parameter of the :doc:`configuration <configuration>`.
|
||||
|
||||
This namespace is a bit special, it can access variables in another namespace.
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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 <dictionaries>`.
|
||||
|
||||
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 <dictionaries>` (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 <dictionary>` 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 <dictionary>` example with a variable into it:
|
|||
---
|
||||
proxy_mode:
|
||||
|
||||
:download:`source file <https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_010/firefox/00-proxy.yml>`
|
||||
|
||||
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
|
||||
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, <name> " 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.
|
||||
|
||||
|
|
|
|||
|
|
@ -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 <https://fr.wikipedia.org/wiki/Rougail>`_ from the Mauritius and Reunion Islands,
|
||||
|
||||
- it is also a `Python3 <https://www.python.org/>`_ library which enables us to conveniently load application :term:`variable`\ s in a simple `YAML <https://yaml.org/>`_ 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 <https://www.python.org/>`_ library which enables us to conveniently load application :term:`variable`\ s in a simple `YAML <https://yaml.org/>`_ 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.
|
||||
|
||||
|
|
|
|||
|
|
@ -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 <https://www.mozilla.org/en-US/firefox/new/>`_ browser
|
||||
*how to set a proxy* in the `Mozilla Firefox <https://www.mozilla.org/en-US/firefox/new/>`_ 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
|
||||
|
||||
|
|
|
|||
|
|
@ -9,13 +9,17 @@ 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 <dictionary>`
|
||||
Define a Rougail :term:`structure description file <dictionary>`
|
||||
|
||||
:ref:`Here is an empty Rougail dictionnary <RougailDictionaryEmptyFile>`
|
||||
https://forge.cloud.silique.fr/stove/rougail-tutorials/src/commit/v1.1_000/firefox/00-proxy.yml
|
||||
|
||||
|
||||
Here is an empty Rougail dictionnary <RougailDictionaryEmptyFile>`
|
||||
|
||||
- define a variable and its default value
|
||||
|
||||
|
|
@ -29,7 +33,6 @@ Preliminaries
|
|||
|
||||
:ref:`Here is a Rougail variable with a default value <RougailDictionaryFirstVariableDefault>`
|
||||
|
||||
|
||||
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.
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
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 this is not just about typing.
|
||||
|
||||
Name
|
||||
But consitency handling system is is not just about strong typing. It is more than that.
|
||||
|
||||
Names
|
||||
------
|
||||
|
||||
Variable name
|
||||
|
||||
Variable's associated symbolic name.
|
||||
|
||||
It's best to follow the :ref:`convention on variable names`.
|
||||
.. seealso::
|
||||
|
||||
Have a look at the :ref:`convention on variable naming link <convention on variable names>`.
|
||||
|
||||
Shorthand declaration
|
||||
----------------------------
|
||||
|
|
|
|||
Loading…
Reference in a new issue