diff --git a/docs/concepts.rst b/docs/concepts.rst index 15d0797f0..4dbc61c2f 100644 --- a/docs/concepts.rst +++ b/docs/concepts.rst @@ -1,44 +1,329 @@ Abstract presentation ========================= -Why another validating library? +Rougail, a powerful, free/open-source configuration language that combines declaration, data validation, and templating in a single, declarative syntax. + +Why another configuration manager? ------------------------------------- -Using Rougail in your application or your python libraries can tansform end user consumer defined consistency rules into highly consistent business objects. +Using Rougail tansform end user consumer defined consistency rules into highly consistent business objects. +It's a configuration language designed to simplify and unify the way you define, validate, and generate configuration data. -We then have to say that the handling system used to ensure the variables integrity is another python library, called :term:`Tiramisu`. Rougail is currently strongly affiliated with Tiramisu. +In other word, making it easier to manage complex configurations across multiple environments. -.. note:: Rougail is currently intended to work in coordination with :term:`Tiramisu` and **is not** intended to be connected with any other consistency handling system. +Rougail is: -Explained differently, Rougail allows you to easily implement an integration of the powerful tiramisu consistency handling system. +- a commandline +- a `Python `_ library +- a description language -What is a consistency handling system ? -------------------------------------------- +What kind of configuration manager? +--------------------------------------------- -.. questions:: Rougail, Tiramisu: What is it all about? +At the time of the design of Rougail, there were structuring choices that defined the functioning of the tool. - **Question**: OK, I have understood that the Rougail library allows me to take advantage of the :xref:`tiramisu` consistency handling library. But what is all this for? What is exactly a consistency handling system? And again, what is this :xref:`Tiramisu library ` used for? +The steps in Rougail can be explain as follows: - **Answer**: Well, we will explain in details what this :xref:`tiramisu` library is and what Rougail is. - - In (very) short: +- loads the variable structure file +- loads the user data +- reads, validates, exports the data - - Rougail is the YAML consistency description of a :term:`context`\ 's situation - - Tiramisu is the consistency engine linter +Structure +~~~~~~~~~ .. glossary:: - Tiramisu + structure file - :xref:`tiramisu` is a consistency handling system that has initially been designed - in the configuration management scope. Until now, - this library is generally used to handle configuration options. + A structure file in the Rougail meaning is a YAML file that describes variables + and their dependencies. + There can be a lot of structure files located in many different folders. - It manages variables and group of variables. In the Tiramisu scope we call - it *options* and *option descriptions*. + Rougail reads all the structure files and loads them into a single object + that represents the whole :term:`context`. - Here is the :xref:`tiramisu documentation `. +User data +~~~~~~~~~ -In the Rougail scope, we call it :term:`variables ` and :term:`families `. -In Rougail, the families and variables are located in the :term:`structure files `. +.. glossary:: + user data + + User datas, as opposed to structured datas, are datas that only concern the assignment of values + and not the consistency of the variables between them. + + The variable's values are also called **user values**. + + The consistency field is outside of the user data scope. + The consistency is handled in the :term:`structured datas `\ 's scope. + +Here a some user data examples: + +- configuration files +- environment variables +- external sources +- command-line options +- a form + +Output +~~~~~~~ + +And some output examples: + +Ensuite on pourra définir sous quelle forme on veut recueillir l'information (Outputs) : + +- un objet Tiramisu +- une extraction JSON +- un export pour l'inventaire Ansible +- de la documetation +- ... +.. list-table:: + :widths: 15 45 + :header-rows: 1 + + * - Step + + * - Structure + + * - User data + + * - Output + +What kind of actor? +--------------------- + +It's clear that Rougail can be used in many contexts. + +Here we'll define actor names. Obviously, these aren't the only possible actors. We're just defining the actors within the Rougail context. Choice your own actor name if you wish to personnalize in your specific context. + +.. list-table:: + :widths: 15 45 + :header-rows: 1 + + * - Step + - Description + - Actor + + * - Structure + - The actor who defines the structure + - Integrator + + * - User data + - The actor who sets the values + - Operator + + * - Output + - The actor who uses the variables with their values + - Operator + +.. glossary:: + + integrator + + An integrator in the Rougail field is the person who writes the :term:`structure files `\ . + He has the responsibility of the integration process, that is, + he defines the variables and the relationship between them, the variables that are allowed + (or not) to be set, and so on. His responsabilites are the **structuration** and the **consistency** + of the organisation of the variables between them. + +.. glossary:: + + operator + + An operator in the Rougail field is the person who assigns :term:`value`\ s to the pre-defined variables, + his responsabilities are to set variable values correctly. + + The user :term:`value`\ s, that is the values that have been set by the operator, are of course type validated. + The type validation is driven by the definitions in the :term:`structure file `. + +Variable lifetime +---------------------- + +Rougail's is a configuration language and data validation tool designed to simplify defining, validating, and generating structured configuration and data. + +Rougail aims to define variables. + +Here we are talking about the variable lifetime. + +The variable’s lifetime is the period between its creation and its destruction. + +The lifecycle of a variable includes the generic stages (like, in the Python language): + +.. list-table:: + :widths: 15 45 + :header-rows: 1 + + * - Creation + - Initialization + - Assignment + - Reading + - Destruction + + * - Variables are assigned a name and a type + - Their first value is assigned + - The variable's value is modified + - The variable's value is used + - The variable terminates upon the destruction of the object + +But other concepts are included in the lifecycle: + +.. list-table:: + :widths: 15 45 + :header-rows: 1 + + * - Documentation + - Permission + - Specialization + + * - Informations for variable documentation like description or help. Those informations are used to build documentation, changelog, ... + - Properties describe access constraints + - Define usage, selection,... + + +.. list-table:: + :widths: 15 45 + :header-rows: 1 + + * - Step + - Actor + - Lifetime + + * - Structure + - Integrator + - Creation + initialization + + * - User data + - Operator + - Assignment + permission + + * - Output + - Operator + - Reading + permission + documentation + specialization + +Mutability +--------------- + +Structure +~~~~~~~~~~~~ + +When the integrator define the structure, variable are mutable. + +Even if the default behavior is to conflict when multiple declarations for the same variable. + +It's possible to explicitly allow to unifying (combined) multiple variables declarations. + +There is no value, strictly speaking. It's a default value. As other parameter, the default value is explicitly mutable. + +User data +~~~~~~~~~~ + +It's no more possible to modifying variable definition. + +The value is now mutable. + +Output +~~~~~~~ + +Variable definition and value setting are immutable. + +.. list-table:: + :widths: 15 45 + :header-rows: 1 + + * - Step + - Actor + - Lifetime + - Variable mutation + - Value mutation + + * - Structure + - Integrator + - Creation + initialization + - Mutable + - N/A + + * - User data + - Operator + - Assignment + permission + - Immutable + - Mutable + + * - Output + - Operator + - Reading + permission + documentation + specialization + - Immutable + - Immutable + +Read write or read only mode +----------------------------- + +.. list-table:: + :widths: 15 45 + :header-rows: 1 + + * - Step + - Actor + - Lifetime + - Variable mutation + - Value mutation + - Read/Write + + * - Structure + - Integrator + - Creation + initialization + - Mutable + - N/A + - N/A + + * - User data + - Operator + - Assignment + permission + - Immutable + - Mutable + - Read write + + * - Output + - Operator + - Reading + permission + documentation + specialization + - Immutable + - Immutable + - Read only + +Access control +----------------- + +.. list-table:: + :widths: 15 45 + :header-rows: 1 + + * - Step + - Actor + - Lifetime + - Variable mutation + - Value mutation + - Read/Write + - Access control + + * - Structure + - Integrator + - Creation + initialization + - Mutable + - N/A + - N/A + - N/A + + * - User data + - Operator + - Assignment + permission + - Immutable + - Mutable + - Read write + - hidden + disabled + + * - Output + - Operator + - Reading + permission + documentation + specialization + - Immutable + - Immutable + - Read only + - disabled + mandatory diff --git a/docs/index.rst b/docs/index.rst index 16f63c7db..3b7675547 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -40,13 +40,14 @@ Rougail - is a `delicious cooked dish `_ from the Mauritius and Reunion Islands, -- 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). +- it is also a tool which enables us to conveniently load :term:`variable`\ s in `YAML `_ file format in such a way that the end user consumer can handle them consistently (that is, against an user-defined consistency). .. toctree:: :titlesonly: :caption: What is it all about concepts + tiramisu tutorial/index .. toctree:: diff --git a/docs/structfile.rst b/docs/structfile.rst index c27e45e8d..348a01b9c 100644 --- a/docs/structfile.rst +++ b/docs/structfile.rst @@ -1,21 +1,6 @@ The structure files ===================== -Definition ------------- - -.. glossary:: - - structure file - - A structure file in the Rougail meaning is a YAML file that describes variables - and their dependencies. - There can be a lot of structure files located in many different folders. - - Rougail reads all the structure files and loads them into a single object - that represents the whole :term:`context`. - - The header of a structure file ----------------------------------- diff --git a/docs/tiramisu.rst b/docs/tiramisu.rst new file mode 100644 index 000000000..1d8eed786 --- /dev/null +++ b/docs/tiramisu.rst @@ -0,0 +1,41 @@ +Link between Rougail and Tiramisu +====================================== + +Is using Tiramisu? +------------------------------------- + +We have to say that the handling system used to ensure the variables integrity is another python library, called :term:`Tiramisu`. Rougail is currently strongly affiliated with Tiramisu. + +.. note:: Rougail is currently intended to work in coordination with :term:`Tiramisu` and **is not** intended to be connected with any other consistency handling system. + +Explained differently, Rougail allows you to easily implement an integration of the powerful :term:`Tiramisu` consistency handling system. + +What is a consistency handling system? +------------------------------------------- + +.. questions:: Rougail, Tiramisu: What is it all about? + + **Question**: OK, I have understood that the Rougail library allows me to take advantage of the :xref:`tiramisu` consistency handling library. 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, we will explain in details what this :xref:`tiramisu` library is and what Rougail is. + + In (very) short: + + - Rougail is the YAML consistency description of a :term:`context`\ 's situation + - Tiramisu is the consistency engine linter + +.. glossary:: + + Tiramisu + + :xref:`tiramisu` is a consistency handling system that has initially been designed + in the configuration management scope. Until now, + this library is generally used to handle configuration options. + + It manages variables and group of variables. In the Tiramisu scope we call + it *options* and *option descriptions*. + + Here is the :xref:`tiramisu documentation `. + +In the Rougail scope, we call it :term:`variables ` and :term:`families `. +In Rougail, the families and variables are located in the :term:`structure files `. diff --git a/docs/tutorial/preliminary.rst b/docs/tutorial/preliminary.rst index ea3dce1ca..f314cc81e 100644 --- a/docs/tutorial/preliminary.rst +++ b/docs/tutorial/preliminary.rst @@ -1,7 +1,7 @@ Getting started ==================== -Presentation of the firefox configuration options +Presentation of the Firefox configuration options -------------------------------------------------- At first glance we can see that we have a selection of five configuration options that we need to fill in, they are highlighted here in this screenshot: @@ -276,44 +276,12 @@ as you read the Rougail's documentation and tutorial. So far we have only talked about the actor that writes the :term:`structure files `\ . The one who writes the structure file plays the *role* of the *integrator*. -.. glossary:: - - integrator - - An integrator in the Rougail field is the person who writes the :term:`structure files `\ . - He has the responsibility of the integration process, that is, - he defines the variables and the relationship between them, the variables that are allowed - (or not) to be set, and so on. His responsabilites are the **structuration** and the **consistency** - of the organisation of the variables between them. - Now we will talk about the one that defines the values. His role is called the operator role. -.. glossary:: - - operator - - An operator in the Rougail field is the person who assigns :term:`value`\ s to the pre-defined variables, - his responsabilities are to set variable values correctly. - - The user :term:`value`\ s, that is the values that have been set by the operator, are of course type validated. - The type validation is driven by the definitions in the :term:`structure file `. - It is the operator's responsibility to set the user data variables values. The operator does not handle the structure files, he is responsible of other files called the :term:`user data files `. -.. glossary:: - - user data - - User datas, as opposed to structured datas, are datas that only concern the assignment of values - and not the consistency of the variables between them. - - The variable's values are also called **user values**. - - The consistency field is outside of the user data scope. - The consistency is handled in the :term:`structured datas `\ 's scope. - .. important:: For now, we don't know how to disable the default `mandatory` settings, so if neither a default value nor a user value are set for a given variable, Rougail will raise an error.