docs(refactoring): refactoring indexes (continuation)
This commit is contained in:
gwen
parent
a18a39425d
commit
570b22525b
9 changed files with 197 additions and 216 deletions
|
|
@ -10,16 +10,10 @@ Rougail
|
|||
|
||||
.. todo:: définir les termes suivants:
|
||||
|
||||
2 check.rst:56: WARNING: term not in glossary: 'follower'
|
||||
4 family.rst:25: WARNING: label non défini: 'convention on variable names'
|
||||
5 structureddata.rst:89: WARNING: term not in glossary: 'variable_namespace'
|
||||
6 tutorial/tutorial.rst:437: WARNING: term not in glossary: 'leadership'
|
||||
7 tutorial/tutorial.rst:546: WARNING: term not in glossary: 'leader'
|
||||
8 tutorial/tutorial.rst:547: WARNING: term not in glossary: 'follower'
|
||||
9 variable.rst:38: WARNING: label non défini: 'convention on variable names'
|
||||
10 variable.rst:137: WARNING: term not in glossary: 'leading'
|
||||
11 variable.rst:154: WARNING: term not in glossary: 'required'
|
||||
13 variable.rst:156: WARNING: term not in glossary: 'follower'
|
||||
|
||||
|
||||
.. todo:: créer les documents suivants:
|
||||
|
|
@ -48,6 +42,7 @@ Rougail
|
|||
:caption: Structured data
|
||||
|
||||
structured_data/index
|
||||
format_content/index
|
||||
tutorial/index
|
||||
|
||||
.. toctree::
|
||||
|
|
|
|||
|
|
@ -1,218 +1,10 @@
|
|||
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
|
||||
:caption: Rougail format's integrity and documentation
|
||||
|
||||
structured_data
|
||||
documentation
|
||||
data_integrity
|
||||
|
||||
The Rougail format
|
||||
--------------------
|
||||
|
||||
Now that we understand what can be described in a structured data file, let's see how to describe variables.
|
||||
|
||||
The variable is described in Rougail format.
|
||||
|
||||
.. toctree::
|
||||
:titlesonly:
|
||||
:caption: Structured data
|
||||
|
||||
variable
|
||||
family
|
||||
path
|
||||
calculation
|
||||
condition
|
||||
validation
|
||||
|
|
|
|||
194
docs/structured_data/structured_data.rst
Normal file
194
docs/structured_data/structured_data.rst
Normal file
|
|
@ -0,0 +1,194 @@
|
|||
The structure file
|
||||
=======================
|
||||
|
||||
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.
|
||||
|
||||
Loading…
Reference in a new issue