docs(refactoring): refactoring indexes
This commit is contained in:
gwen
parent
01504bb244
commit
2508087841
6 changed files with 203 additions and 203 deletions
|
|
@ -47,7 +47,6 @@ Rougail
|
||||||
:titlesonly:
|
:titlesonly:
|
||||||
:caption: Structured data
|
:caption: Structured data
|
||||||
|
|
||||||
structured_data
|
|
||||||
structured_data/index
|
structured_data/index
|
||||||
tutorial/index
|
tutorial/index
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -76,7 +76,7 @@ The Rougail CLI can output a rather complete view of the dataet:
|
||||||
:titlesonly:
|
:titlesonly:
|
||||||
:caption: Use library
|
:caption: Use library
|
||||||
|
|
||||||
user_data
|
user_datas
|
||||||
output
|
output
|
||||||
parse
|
parse
|
||||||
tags
|
tags
|
||||||
|
|
|
||||||
|
|
@ -1,200 +0,0 @@
|
||||||
The structure file and data
|
|
||||||
============================
|
|
||||||
|
|
||||||
What contains exactly a :term:`structure file`?
|
|
||||||
-------------------------------------------------
|
|
||||||
|
|
||||||
.. 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`.
|
|
||||||
|
|
||||||
A :term:`structure file` is a YAML file whose structure is described in this documentation page.
|
|
||||||
|
|
||||||
A structure file contains a set of variables, usable in your application, for example in a template
|
|
||||||
to generate configuration files.
|
|
||||||
|
|
||||||
:term:`Families <family>` and :term:`variables <variable>` can be defined in several structure files. These structure files are then aggregated.
|
|
||||||
|
|
||||||
File naming convention
|
|
||||||
--------------------------
|
|
||||||
|
|
||||||
.. _filenamingconvention:
|
|
||||||
|
|
||||||
The structure files in a given folder
|
|
||||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
||||||
|
|
||||||
For the sake of clarity, we put the structured data in separate files.
|
|
||||||
It's a good way to organize your rougail structures this way,
|
|
||||||
in the real world we need separate files for different topics.
|
|
||||||
|
|
||||||
For example some files like this:
|
|
||||||
|
|
||||||
A file named :file:`firefox/00-proxy.yml` structure file and file named :file:`firefox/10-manual.yml`
|
|
||||||
|
|
||||||
::
|
|
||||||
|
|
||||||
.
|
|
||||||
└── firefox
|
|
||||||
├── 00-proxy.yml
|
|
||||||
└── 10-manual.yml
|
|
||||||
|
|
||||||
.. note:: We of course could have put everything in one file.
|
|
||||||
Again, it is better to separate the structures in different files
|
|
||||||
for reasons of ordering and clarity.
|
|
||||||
|
|
||||||
Ordering your structure files
|
|
||||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
||||||
|
|
||||||
The order in which files are loaded is important in Rougail.
|
|
||||||
In a given folder, files are loaded in alphabetical order.
|
|
||||||
|
|
||||||
Furthermore, for better readability of the order in which files are
|
|
||||||
loaded into a folder, we have adopted a convention.
|
|
||||||
To facilitate classification, we have defined a standard notation for structure file names:
|
|
||||||
|
|
||||||
::
|
|
||||||
|
|
||||||
XX-<name>.yml
|
|
||||||
|
|
||||||
Where `XX` is a two digits integer followed by an hyphen, and `<name>` is a name that describes
|
|
||||||
the structure that is in this file. We advise you to adopt this convention as well.
|
|
||||||
|
|
||||||
File naming convention
|
|
||||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
||||||
|
|
||||||
There is no restriction to the `<name>` name part of file name. But it is preferable to only use
|
|
||||||
lowercase ASCII letters, numbers and the `"_"` (undescore) character.
|
|
||||||
|
|
||||||
.. FIXME: et le moins "-" aussi non ?
|
|
||||||
|
|
||||||
.. _namespace:
|
|
||||||
|
|
||||||
Separation of structures into namespaces
|
|
||||||
----------------------------------------
|
|
||||||
|
|
||||||
.. glossary::
|
|
||||||
|
|
||||||
namespace
|
|
||||||
|
|
||||||
A namespace is a way to organize and group related variables under a unique name.
|
|
||||||
|
|
||||||
It enables us to:
|
|
||||||
|
|
||||||
- avoid naming conflicts
|
|
||||||
- permit logical grouping: related variables can be grouped together
|
|
||||||
- scope control: namespaces limit the visibility of variable to the namespace itself
|
|
||||||
|
|
||||||
By default there is no namespace.
|
|
||||||
|
|
||||||
.. _defaultnamespace:
|
|
||||||
|
|
||||||
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 (the default 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.
|
|
||||||
|
|
||||||
The header of a structure file
|
|
||||||
-----------------------------------
|
|
||||||
|
|
||||||
A basic structure file is composed of:
|
|
||||||
|
|
||||||
- a YAML 1.2 standard header
|
|
||||||
- a version attribute
|
|
||||||
|
|
||||||
.. code-block:: yaml
|
|
||||||
|
|
||||||
%YAML 1.2
|
|
||||||
---
|
|
||||||
version: 1.1
|
|
||||||
...
|
|
||||||
|
|
||||||
The structure file processing
|
|
||||||
----------------------------------
|
|
||||||
|
|
||||||
The :term:`structure files <structure file>` contain information that will be used by the consistency handling system for structure validation.
|
|
||||||
This is what we call :term:`structured data` writen in :term:`Rougail format`.
|
|
||||||
|
|
||||||
.. figure:: images/schema.png
|
|
||||||
:alt: The Rougail process
|
|
||||||
:align: center
|
|
||||||
|
|
||||||
The Rougail process from structure files to :term:`Tiramisu` valition handler object
|
|
||||||
|
|
||||||
A variable-first DSL
|
|
||||||
-----------------------
|
|
||||||
|
|
||||||
All of the declaring variables and writing consistency is as simple as writing YAML.
|
|
||||||
|
|
||||||
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 :term:`Tiramisu` consistency management tool can check the consistency of the variables between them.
|
|
||||||
|
|
||||||
.. glossary::
|
|
||||||
|
|
||||||
DSL
|
|
||||||
|
|
||||||
A DSL stands for **Domain-Specific Language**, it is a programming or markup language designed for a specific application domain.
|
|
||||||
Unlike general-purpose languages (like Python or Java), DSLs are optimized for a narrow set of problems, offering concise syntax and specialized features tailored to their domain.
|
|
||||||
|
|
||||||
Rougail format
|
|
||||||
|
|
||||||
The Rougail format (or :term:`structured data`) is a DSL (Domain-Specific Language) designed for describing variables and their consistency.
|
|
||||||
|
|
||||||
Declarative abstraction
|
|
||||||
-----------------------
|
|
||||||
|
|
||||||
The variables are described using a declarative model.
|
|
||||||
This means that the user simply defines the desired final state of the variable.
|
|
||||||
:term:`Tiramisu` will then determine the actions necessary to reach that state.
|
|
||||||
|
|
||||||
In other words, the user defines the variable schema, which will then be applied deterministically.
|
|
||||||
|
|
||||||
The language is a mix of YAML 1.2 and Jinja Templating.
|
|
||||||
|
|
||||||
Each variables are declared in a mapping object in YAML (the keys are variable properties).
|
|
||||||
|
|
||||||
There is an execption. That what we call the short-hand declaration.
|
|
||||||
|
|
||||||
.. glossary::
|
|
||||||
|
|
||||||
Short-hand notation
|
|
||||||
|
|
||||||
Shorthand notation allows you to condense as much information as possible when creating a variable.
|
|
||||||
Generally, the declaration is done on a single line (or at most, a very small number of lines).
|
|
||||||
|
|
||||||
Of course, it's not possible to fully customize the variable with this notation.
|
|
||||||
|
|
||||||
Use shorthand notation whenever possible. This makes the file easier to read.
|
|
||||||
|
|
||||||
Versioned format
|
|
||||||
----------------
|
|
||||||
|
|
||||||
The format can evolve. This means that parameters can be added, removed, or modified.
|
|
||||||
When writing structured data, you must always specify the format version.
|
|
||||||
You must also ensure that your Rougail version is compatible with your format version.
|
|
||||||
|
|
||||||
.. toctree::
|
|
||||||
:titlesonly:
|
|
||||||
:caption: Structured data
|
|
||||||
|
|
||||||
structured_data/documentation
|
|
||||||
structured_data/data_integrity
|
|
||||||
|
Before Width: | Height: | Size: 37 KiB After Width: | Height: | Size: 37 KiB |
|
Before Width: | Height: | Size: 26 KiB After Width: | Height: | Size: 26 KiB |
|
|
@ -1,5 +1,206 @@
|
||||||
|
The structure file and data
|
||||||
|
============================
|
||||||
|
|
||||||
|
What contains exactly a :term:`structure file`?
|
||||||
|
-------------------------------------------------
|
||||||
|
|
||||||
|
.. 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`.
|
||||||
|
|
||||||
|
A :term:`structure file` is a YAML file whose structure is described in this documentation page.
|
||||||
|
|
||||||
|
A structure file contains a set of variables, usable in your application, for example in a template
|
||||||
|
to generate configuration files.
|
||||||
|
|
||||||
|
:term:`Families <family>` and :term:`variables <variable>` can be defined in several structure files. These structure files are then aggregated.
|
||||||
|
|
||||||
|
File naming convention
|
||||||
|
--------------------------
|
||||||
|
|
||||||
|
.. _filenamingconvention:
|
||||||
|
|
||||||
|
The structure files in a given folder
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
For the sake of clarity, we put the structured data in separate files.
|
||||||
|
It's a good way to organize your rougail structures this way,
|
||||||
|
in the real world we need separate files for different topics.
|
||||||
|
|
||||||
|
For example some files like this:
|
||||||
|
|
||||||
|
A file named :file:`firefox/00-proxy.yml` structure file and file named :file:`firefox/10-manual.yml`
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
.
|
||||||
|
└── firefox
|
||||||
|
├── 00-proxy.yml
|
||||||
|
└── 10-manual.yml
|
||||||
|
|
||||||
|
.. note:: We of course could have put everything in one file.
|
||||||
|
Again, it is better to separate the structures in different files
|
||||||
|
for reasons of ordering and clarity.
|
||||||
|
|
||||||
|
Ordering your structure files
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
The order in which files are loaded is important in Rougail.
|
||||||
|
In a given folder, files are loaded in alphabetical order.
|
||||||
|
|
||||||
|
Furthermore, for better readability of the order in which files are
|
||||||
|
loaded into a folder, we have adopted a convention.
|
||||||
|
To facilitate classification, we have defined a standard notation for structure file names:
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
XX-<name>.yml
|
||||||
|
|
||||||
|
Where `XX` is a two digits integer followed by an hyphen, and `<name>` is a name that describes
|
||||||
|
the structure that is in this file. We advise you to adopt this convention as well.
|
||||||
|
|
||||||
|
File naming convention
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
There is no restriction to the `<name>` name part of file name. But it is preferable to only use
|
||||||
|
lowercase ASCII letters, numbers and the `"_"` (undescore) character.
|
||||||
|
|
||||||
|
.. FIXME: et le moins "-" aussi non ?
|
||||||
|
|
||||||
|
.. _namespace:
|
||||||
|
|
||||||
|
Separation of structures into namespaces
|
||||||
|
----------------------------------------
|
||||||
|
|
||||||
|
.. glossary::
|
||||||
|
|
||||||
|
namespace
|
||||||
|
|
||||||
|
A namespace is a way to organize and group related variables under a unique name.
|
||||||
|
|
||||||
|
It enables us to:
|
||||||
|
|
||||||
|
- avoid naming conflicts
|
||||||
|
- permit logical grouping: related variables can be grouped together
|
||||||
|
- scope control: namespaces limit the visibility of variable to the namespace itself
|
||||||
|
|
||||||
|
By default there is no namespace.
|
||||||
|
|
||||||
|
.. _defaultnamespace:
|
||||||
|
|
||||||
|
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 (the default 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.
|
||||||
|
|
||||||
|
The header of a structure file
|
||||||
|
-----------------------------------
|
||||||
|
|
||||||
|
A basic structure file is composed of:
|
||||||
|
|
||||||
|
- a YAML 1.2 standard header
|
||||||
|
- a version attribute
|
||||||
|
|
||||||
|
.. code-block:: yaml
|
||||||
|
|
||||||
|
%YAML 1.2
|
||||||
|
---
|
||||||
|
version: 1.1
|
||||||
|
...
|
||||||
|
|
||||||
|
The structure file processing
|
||||||
|
----------------------------------
|
||||||
|
|
||||||
|
The :term:`structure files <structure file>` contain information that will be used by the consistency handling system for structure validation.
|
||||||
|
This is what we call :term:`structured data` writen in :term:`Rougail format`.
|
||||||
|
|
||||||
|
.. figure:: images/schema.png
|
||||||
|
:alt: The Rougail process
|
||||||
|
:align: center
|
||||||
|
|
||||||
|
The Rougail process from structure files to :term:`Tiramisu` valition handler object
|
||||||
|
|
||||||
|
A variable-first DSL
|
||||||
|
-----------------------
|
||||||
|
|
||||||
|
All of the declaring variables and writing consistency is as simple as writing YAML.
|
||||||
|
|
||||||
|
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 :term:`Tiramisu` consistency management tool can check the consistency of the variables between them.
|
||||||
|
|
||||||
|
.. glossary::
|
||||||
|
|
||||||
|
DSL
|
||||||
|
|
||||||
|
A DSL stands for **Domain-Specific Language**, it is a programming or markup language designed for a specific application domain.
|
||||||
|
Unlike general-purpose languages (like Python or Java), DSLs are optimized for a narrow set of problems, offering concise syntax and specialized features tailored to their domain.
|
||||||
|
|
||||||
|
Rougail format
|
||||||
|
|
||||||
|
The Rougail format (or :term:`structured data`) is a DSL (Domain-Specific Language) designed for describing variables and their consistency.
|
||||||
|
|
||||||
|
Declarative abstraction
|
||||||
|
-----------------------
|
||||||
|
|
||||||
|
The variables are described using a declarative model.
|
||||||
|
This means that the user simply defines the desired final state of the variable.
|
||||||
|
:term:`Tiramisu` will then determine the actions necessary to reach that state.
|
||||||
|
|
||||||
|
In other words, the user defines the variable schema, which will then be applied deterministically.
|
||||||
|
|
||||||
|
The language is a mix of YAML 1.2 and Jinja Templating.
|
||||||
|
|
||||||
|
Each variables are declared in a mapping object in YAML (the keys are variable properties).
|
||||||
|
|
||||||
|
There is an execption. That what we call the short-hand declaration.
|
||||||
|
|
||||||
|
.. glossary::
|
||||||
|
|
||||||
|
Short-hand notation
|
||||||
|
|
||||||
|
Shorthand notation allows you to condense as much information as possible when creating a variable.
|
||||||
|
Generally, the declaration is done on a single line (or at most, a very small number of lines).
|
||||||
|
|
||||||
|
Of course, it's not possible to fully customize the variable with this notation.
|
||||||
|
|
||||||
|
Use shorthand notation whenever possible. This makes the file easier to read.
|
||||||
|
|
||||||
|
Versioned format
|
||||||
|
----------------
|
||||||
|
|
||||||
|
The format can evolve. This means that parameters can be added, removed, or modified.
|
||||||
|
When writing structured data, you must always specify the format version.
|
||||||
|
You must also ensure that your Rougail version is compatible with your format version.
|
||||||
|
|
||||||
|
.. toctree::
|
||||||
|
:titlesonly:
|
||||||
|
:caption: Structured data
|
||||||
|
|
||||||
|
documentation
|
||||||
|
data_integrity
|
||||||
|
|
||||||
The Rougail format
|
The Rougail format
|
||||||
==================
|
--------------------
|
||||||
|
|
||||||
Now that we understand what can be described in a structured data file, let's see how to describe variables.
|
Now that we understand what can be described in a structured data file, let's see how to describe variables.
|
||||||
|
|
||||||
|
|
|
||||||
Loading…
Reference in a new issue