diff --git a/docs/index.rst b/docs/index.rst index 24713124b..3ee0dada7 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -47,7 +47,6 @@ Rougail :titlesonly: :caption: Structured data - structured_data structured_data/index tutorial/index diff --git a/docs/library/index.rst b/docs/library/index.rst index f35226b3b..b3dc1234d 100644 --- a/docs/library/index.rst +++ b/docs/library/index.rst @@ -76,7 +76,7 @@ The Rougail CLI can output a rather complete view of the dataet: :titlesonly: :caption: Use library - user_data + user_datas output parse tags diff --git a/docs/structured_data.rst b/docs/structured_data.rst deleted file mode 100644 index 832228065..000000000 --- a/docs/structured_data.rst +++ /dev/null @@ -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 ` and :term:`variables ` 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-.yml - -Where `XX` is a two digits integer followed by an hyphen, and `` 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 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 ` parameter of the :doc:`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 `. - -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 ` 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 diff --git a/docs/images/schema.png b/docs/structured_data/images/schema.png similarity index 100% rename from docs/images/schema.png rename to docs/structured_data/images/schema.png diff --git a/docs/images/schema.svg b/docs/structured_data/images/schema.svg similarity index 100% rename from docs/images/schema.svg rename to docs/structured_data/images/schema.svg diff --git a/docs/structured_data/index.rst b/docs/structured_data/index.rst index 2b3920a24..ba010f7c3 100644 --- a/docs/structured_data/index.rst +++ b/docs/structured_data/index.rst @@ -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 ` and :term:`variables ` 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-.yml + +Where `XX` is a two digits integer followed by an hyphen, and `` 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 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 ` parameter of the :doc:`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 `. + +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 ` 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 -================== +-------------------- Now that we understand what can be described in a structured data file, let's see how to describe variables.