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.
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
-----------------
|
||||
|
||||
|
|
|
|||
|
|
@ -45,7 +45,7 @@ Rougail
|
|||
:titlesonly:
|
||||
:caption: The dictionaries
|
||||
|
||||
dictionary
|
||||
structfile
|
||||
dict_convention
|
||||
|
||||
.. 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
|
||||
=====================================
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue