getting started removal
This commit is contained in:
gwen
parent
f3c3fe4df0
commit
8912e6dd63
7 changed files with 147 additions and 95 deletions
44
docs/concepts.rst
Normal file
44
docs/concepts.rst
Normal file
|
|
@ -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 <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 <tiramisu>`.
|
||||||
|
|
||||||
|
In the Rougail scope, we call it :term:`variables <variable>` and :term:`families <family>`.
|
||||||
|
In Rougail, the families and variables are located in the :term:`structure files <structure file>`.
|
||||||
|
|
||||||
|
|
@ -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.
|
The files must therefore be started with two numbers followed by a hyphen.
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -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 <variable_namespace>` parameter of the :doc:`configuration <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 <configuration>`.
|
|
||||||
|
|
||||||
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.
|
|
||||||
|
|
@ -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 <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
|
The variables
|
||||||
-----------------
|
-----------------
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -45,7 +45,7 @@ Rougail
|
||||||
:titlesonly:
|
:titlesonly:
|
||||||
:caption: The dictionaries
|
:caption: The dictionaries
|
||||||
|
|
||||||
dictionary
|
structfile
|
||||||
dict_convention
|
dict_convention
|
||||||
|
|
||||||
.. toctree::
|
.. toctree::
|
||||||
|
|
|
||||||
96
docs/structfile.rst
Normal file
96
docs/structfile.rst
Normal file
|
|
@ -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 <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. <tutorial>`
|
||||||
|
|
||||||
|
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 <variable_namespace>` parameter of the :doc:`configuration <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 <configuration>`.
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
@ -1,3 +1,5 @@
|
||||||
|
.. _tutorial:
|
||||||
|
|
||||||
Tutorial with a real world sample
|
Tutorial with a real world sample
|
||||||
=====================================
|
=====================================
|
||||||
|
|
||||||
|
|
|
||||||
Loading…
Reference in a new issue