diff --git a/docs/concepts.rst b/docs/concepts.rst new file mode 100644 index 000000000..15d0797f0 --- /dev/null +++ b/docs/concepts.rst @@ -0,0 +1,44 @@ +Abstract presentation +========================= + +Why another validating library? +------------------------------------- + +Using Rougail in your application or your python libraries can tansform end user consumer defined consistency rules into highly consistent business objects. + +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. + +.. 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 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/dict_convention.rst b/docs/dict_convention.rst index 2cef856a5..8cb4efcd9 100644 --- a/docs/dict_convention.rst +++ b/docs/dict_convention.rst @@ -1,10 +1,10 @@ -Dictionary conventions -========================= +Structure file conventions +============================ -Dictionary file naming convention +Structure file naming convention ------------------------------------ -The order of dictionaries is important for the order in which variables and families are created. +The order of structure files is important for the order in which variables and families are created. The files must therefore be started with two numbers followed by a hyphen. diff --git a/docs/dictionary.rst b/docs/dictionary.rst deleted file mode 100644 index 5483dbfb1..000000000 --- a/docs/dictionary.rst +++ /dev/null @@ -1,36 +0,0 @@ -The structure files -===================== - -What do you mean by :term:`structure file`? -------------------------------------------- - -A :term:`structure file` is a YAML file whose structure is described in this documentation page. - -A structure file contains a set of variables loaded into :term:`Tiramisu`, usable at any time, especially in a :term:`templates`. - -:term:`Families` and :term:`variables` can be defined in several structure files. These structure files are then aggregated. - -Structure files are loaded in the directory order defined by the `dictionaries_dir` configuration parameter. -Each directory is loaded one after the other. -Inside these directories the YAML files will be classified in alphabetical order. - -There is no alphabetical ordering of all YAML files in all directories. - -It is also possible to :term:`redefine` elements to change the behavior of a family or a variable. - -The default namespace -------------------------- - -The families and variables contained in these structure files 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. - -The extra structure files ---------------------------- - -An extra is a different namespace. The idea is to be able to classify the variables by theme. - -Extra namespaces must be declared :doc:`when configuring Rougail `. - -In this namespace we cannot access variables from another `extra` namespace. -On the other hand, it is possible to access the variable of the default namespace. diff --git a/docs/gettingstarted.rst b/docs/gettingstarted.rst index 206121bc3..e92dbbc40 100644 --- a/docs/gettingstarted.rst +++ b/docs/gettingstarted.rst @@ -1,57 +1,3 @@ - -The structure files ---------------------- - -.. 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`. - - -.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_000/firefox/00-proxy.yml - :language: yaml - :caption: An empty Rougail structure file. - :name: RougailStructureFirstVariableDescription - -.. - %YAML 1.2 - --- - version: 1.1 - ... - -.. figure:: images/schema.png - :alt: The Rougail process - :align: center - - The Rougail process from structure files to Tiramisu object - -.. glossary:: - - structured data - - We sometimes call 'structured datas' the datas that are in the structure files, - as opposed to :term:`user datas `\ . - For example when a value of a variable is defined in the structured datas, that is - in a structured file, the assigned value's status is that the variable's value is a default value. - If the assigned value of the variable is defined in a user data file, - it is an user assigned value. - -We'll see later on some examples of default values and user assigned values. - -The main advantage of all of this 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 style (that is, in a YAML file). - -Once the structure files are loaded by Rougail, the Tiramisu configuration management tool can check the consistency of the variables between them. - The variables ----------------- diff --git a/docs/index.rst b/docs/index.rst index 399930eeb..9cd88febc 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -45,7 +45,7 @@ Rougail :titlesonly: :caption: The dictionaries - dictionary + structfile dict_convention .. toctree:: diff --git a/docs/structfile.rst b/docs/structfile.rst new file mode 100644 index 000000000..cc139e9f0 --- /dev/null +++ b/docs/structfile.rst @@ -0,0 +1,96 @@ +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 +----------------------------------- + +.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_000/firefox/00-proxy.yml + :language: yaml + :caption: An empty Rougail structure file. + :name: RougailStructureFirstVariableDescription + +.. + %YAML 1.2 + --- + version: 1.1 + ... + +The structure file processing +---------------------------------- + +The structured files contain information that will be used by the consistency +handling system for structure validation. + +.. figure:: images/schema.png + :alt: The Rougail process + :align: center + + The Rougail process from structure files to Tiramisu valition handler object + +The structured data +--------------------- + +.. glossary:: + + structured data + + We sometimes call "structured datas" the datas that are defined in the structure files, + as opposed to :term:`user datas `\ . + For example when a value of a variable is defined in the structured datas, that is + in a structured file, the assigned value's status is that the variable's value is a default value. + If the assigned value of the variable is defined in a user data file, + it is an user assigned value. + +We'll see later on some examples of default values and user assigned values. + +The main advantage of all of this 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 style (that is, in a YAML file). + +Once the structure files are loaded by Rougail, the Tiramisu configuration management tool can check the consistency of the variables between them. + +What contains exactly a :term:`structure file`? +------------------------------------------------- + +A :term:`structure file` is a YAML file whose structure is described in this documentation page. + +A structure file contains a set of variables loaded into :term:`Tiramisu`, usable in your application, for example in a :term:`template` +to generate configuration files. + +:term:`Families` and :term:`variables` can be defined in several structure files. These structure files are then aggregated. + +If you want to see the contents of a structure file, you can have a look at the :ref:`tutorial with a real world sample. ` + +The default namespace +------------------------- + +The families and variables contained in these structure files 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. + +The extra structure files +--------------------------- + +An extra is a different namespace. The idea is to be able to classify the variables by theme. + +Extra namespaces must be declared :doc:`when configuring Rougail `. + +In this namespace we cannot access variables from another `extra` namespace. +On the other hand, it is possible to access the variable of the default namespace. diff --git a/docs/tutorial/index.rst b/docs/tutorial/index.rst index 87cd64b2a..df44d30b1 100644 --- a/docs/tutorial/index.rst +++ b/docs/tutorial/index.rst @@ -1,3 +1,5 @@ +.. _tutorial: + Tutorial with a real world sample =====================================