stove/rougail
3
0
Fork 0
Code Issues 5 Pull requests 1 Projects Releases Wiki Activity

docs(structured-data): proofreading

Browse source
This commit is contained in:
gwen 2026-06-08 18:48:12 +02:00
parent 5386fa5178
commit c50ce5bcc5
5 changed files with 62 additions and 50 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

15
docs/abstract.rst
View file

@ -34,7 +34,7 @@ In other word, making it easier to manage complex configurations across multiple
You might tell me that other configuration management tools do the same thing. And that's partly true.
But Rougail adds interesting features in variable management that other projects don't have.
I am of course referring to the documentation management included directly in the configuration manager.
We are of course referring to the documentation management included directly in the configuration manager.
Your configuration is therefore consistent, easily accessible, and modifiable.
@ -48,8 +48,8 @@ that defined the functioning of the tool.
The steps in Rougail can be explained as follows:
- loading the variable's structured data
- loading the user data
- loading the variable's :term:`structured data`
- loading the :term:`user data`
- reading, validating, exporting, documenting (and so on...) the data
Structured data
@ -66,7 +66,8 @@ Structured data is also called the Rougail format.
The language is a mix of YAML and Jinja Templating.
It goes beyond traditional schema languages (like JSON Schema, OpenAPI, Cuelang)
It goes beyond traditional schema languages (like `JSON Schema <https://json-schema.org/>`_,
`OpenAPI <https://www.openapis.org/>`_, `Cuelang <https://cuelang.org/>`_)
by combinig type systems, powerful validation, consistency of the configuration and documentation.
Structured data are commonly placed in :term:`structure files <structure file>`.
@ -151,7 +152,7 @@ Choice your own actor name if you wish to personnalize in your specific context.
An operator in the Rougail field is the person who assigns :term:`value`\ s to the pre-defined variables,
his responsabilities are to set variable values correctly.
The user :term:`value`\ s, that is the values that have been set by the operator, are of course type validated.
The user :term:`value`\ s, that is the values that have been set by the :term:`operator`, are of course type validated.
The type validation is driven by the definitions in the :term:`structure file <structure file>`.
Here is a reminder of the different steps:
@ -356,7 +357,7 @@ There are two main properties.
Hidden variable
~~~~~~~~~~~~~~~
A `hidden` variable is a variable whose value cannot be modified by the operator.
A `hidden` variable is a variable whose value cannot be modified by the :term:`operator`.
This could be an internal variable used by the :term:`integrator` that is not supposed to change.
@ -367,7 +368,7 @@ Or a variable that only makes sense in a particular context. Therefore, this var
Disabled variable
~~~~~~~~~~~~~~~~~
A `disabled` variable is a variable that will not be accessible to any of the actors (integrator and operator).
A `disabled` variable is a variable that will not be accessible to any of the actors (:term:`integrator` and :term:`operator`).
This property is generally used dynamically to remove access to the variable depending on the context.

14
docs/structured_data.rst
View file

@ -69,9 +69,11 @@ the structure that is in this file. We advise you to adopt this convention as we
File naming convention
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The is no restriction to the `<name>` name part of file name. But it is preferable to only use
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
@ -133,7 +135,7 @@ This is what we call :term:`structured data` writen in Rougail format.
:alt: The Rougail process
:align: center
The Rougail process from structure files to Tiramisu valition handler object
The Rougail process from structure files to :term:`Tiramisu` valition handler object
A variable-first DSL
-----------------------
@ -142,7 +144,7 @@ All of the declaring variables and writing consistency is as simple as writing Y
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.
Once the structure files are loaded by Rougail, the :term:`Tiramisu` consistency management tool can check the consistency of the variables between them.
.. glossary::
@ -151,20 +153,20 @@ Once the structure files are loaded by Rougail, the Tiramisu configuration manag
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 (or :term:`structured data`) is a DSL (Domain-Specific Language) designed for describing variables and consistency.
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.
Tiramisu will then determine the actions necessary to reach that state.
: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 declaring in a mapping object in YAML (the keys are variable properties).
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.

69
docs/structured_data/data_integrity.rst
View file

@ -27,12 +27,12 @@ Rougail is a strongly-typed DSL.
This means that loading user data requires attention to the variable types.
The :term:`integrator` define the variable type and :term:`operator` has to conform with it.
The :term:`integrator` define the variable type and the :term:`operator` has to conform with it.
.. For untyped user data (such as environment variables), the value type will be adapted during preprocessing.
Dynamicly-typed
'''''''''''''''
Dynamicaly-typed
'''''''''''''''''
During the structured data definition, the type is dynamic.
@ -49,7 +49,7 @@ Type inference
Type inference is the process where Rougail automatically figures out the types without explicit annotations.
In fact, the variable type comes from the type of its default value.
The type inference is in particular use in :term:`short-hand notation`.
The type inference is in particular use with the :term:`short-hand notation`.
Variables typing
~~~~~~~~~~~~~~~~
@ -59,15 +59,17 @@ Standard types
Rougail accepts the following standard types:
- string (default type of a variable)
- integer
- float
- boolean
- `string` (default type of a variable)
- `integer`
- `float`
- `boolean`
.. FIXME: est-ce que integer et float -> number type ????
.. seealso:: :doc:`the variable documentation <variable>`
Specialized type
''''''''''''''''
Specialized types
''''''''''''''''''
But we will also find a whole series of specialized types:
@ -85,7 +87,7 @@ A variable with a list of possible values
Sometimes a variable can only hold a finite list of possible values. We call it a variable with a list of possible values.
.. seealso:: tutorial with a real world sample :doc:`variable with a list of possible values <../tutorial/choice>`
.. seealso:: The tutorial with a real world sample about :doc:`a variable with a list of possible values <../tutorial/choice>`
Type parameters
'''''''''''''''
@ -106,7 +108,7 @@ Therefore, it is necessary to provide a simple way to create these custom types.
There are two ways to create a type:
- creating a :term:`Tiramisu` type
- creating a type from an existing variable, see the tutorial with a real world sample :doc:`custom type <../tutorial/customtype>`.
- creating a type from an existing variable, have a look at the tutorial with a real world sample :doc:`custom type <../tutorial/customtype>`.
Nullable variable
'''''''''''''''''
@ -120,19 +122,19 @@ Even if all types can accept this value, by default, they do not.
In reality, the variable not nullable with the value to `null` is not accessible in `read-only` mode (which is the case during the output steps).
In `read/write` mode, the access is indeed granted.
.. seealso:: tutorial with a real world sample :doc:`nullable variable <../tutorial/nullable>`
.. seealso:: The tutorial with a real world sample about a :doc:`nullable variable <../tutorial/nullable>`
The `list` type
'''''''''''''''
A list is not a type either.
It is a property of a variable.
This means that all type could have multiple value by a list can only contain values of an uniq type.
It is a property of a variable. There is no such thing as a container type (like a python `list` type for instance).
This means that all type can have multiple values in a list but it can only contain values of an unique type.
A multiple variable could be nullable. This means that `null` can be accepted as a value in the list (not permitted by default).
But the multiple variable could also be without value (not permitted too by default).
.. seealso:: tutorial with a real world sample :doc:`multiple variable <../tutorial/multiple>`
.. seealso:: The tutorial with a real world sample about a :doc:`multiple variable <../tutorial/multiple>`
Families typing
~~~~~~~~~~~~~~~
@ -150,12 +152,13 @@ This is a JSON example:
"my_variable": "my_value"
}
In Rougail the mapping type is call :term:`family`.
In Rougail the mapping type is called a :term:`family`.
It is a container designed to hold variables.
Families manage the tree structure. It is possible to create subfamilies.
The whole :term:`configuration` tree structure is handled by the families definitions.
It is possible to create subfamilies.
.. seealso:: :doc:`the family documentation <family>`
.. seealso:: The tutorial with a real world sample about :doc:`the family documentation <family>`
The dynamically built family
''''''''''''''''''''''''''''
@ -166,11 +169,11 @@ A dynamically built family is a special family.
dynamically built family
A dynamically built family is a fictitious family linked to a list of uniq identifiers.
A dynamically built family is a fictitious family linked to a list of unique identifiers.
This means that families will appear or disappear folling the context.
This means that families will appear or disappear folling the :term:`context`.
.. seealso:: :doc:`the dynamically built family documentation <family>`
.. seealso:: The tutorial with a real world sample about :doc:`the dynamically built family documentation <family>`
Homogeneous elements sequence
'''''''''''''''''''''''''''''
@ -207,22 +210,26 @@ But it is possible to add additional validations.
For example, one might want numbers, but only odd numbers.
.. index:: overall coherence
Overall coherence
-----------------
An isolated variable can be considered to be of quality but become inconsistent depending on the context.
.. index:: consistency
Consistency
~~~~~~~~~~~
For example, if a minimum value and then a maximum value are requested, the minimum must be less than the maximum.
For example, if a minimum value and then a maximum value are requested, the minimum must be lesser than the maximum.
Overall consistency is initially managed by personality validators who will validate the value of a variable in relation to others.
Overall consistency is initially managed by personalized validators which will validate the value of a variable in relation to others.
Access control
~~~~~~~~~~~~~~
Access control is implemented as soon as an attempt is made to access a variable.
Access control occurs as soon as an attempt is made to access a variable.
There are two main types of access control:
@ -234,12 +241,14 @@ Properties
We already see the property access control.
Remember, we talked about the :ref:`hidden` and :ref:`disabled` variables.
Remember, we talked about the :ref:`hidden variable <hidden>` and :ref:`disabled variable <disabled>` variables.
These properties become fully meaningful when managing overall consistency.
Why ask for the domain name of a service if we haven't activated that service just before?
.. index:: mode
Mode
''''
@ -249,8 +258,8 @@ Let's start by defining what we want to do with the modes.
We'll present a common example, but you'll need to define your own modes according to your needs.
Here is our classic case of mode definition. We'll use three modes:
Here is our classic use case of mode definition. We'll use three modes:
- basic: automatically sets mandatory variables without default values (in this case, the actor adapting the configuration will have to enter values) and manually sets variables that the actor defining the variables deems necessary.
- standard: automatically sets all other variables
- advanced: sets variables that the actor defining the variables decides to include. These variables are intended for a knowledgeable audience who know what to do.
- `basic`: automatically sets mandatory variables without default values (in this case, the actor adapting the configuration will have to enter values) and manually sets variables that the actor defining the variables deems necessary.
- `standard`: automatically sets all other variables
- `advanced`: sets variables that the actor defining the variables decides to include. These variables are intended for a knowledgeable audience who know what to do.

12
docs/structured_data/documentation.rst
View file

@ -1,9 +1,9 @@
Data documentation
==================
Documentation is an integral part of the definition of structured data.
Documentation is an integral part of the definition of :term:`structured data`.
In a sense, we talk about :term:`structured data` and not `schema` in Rougail because the documentation is an integral part of the variable definition.
In a sense, we talk about :term:`structured data` and not `schema` in Rougail because the documentation is an full part of the variable definition.
More broadly, considering the use of a :term:`VaC` tool has the advantage of eliminating the need to manage documentation oneself.
@ -56,14 +56,14 @@ Examples is a property that only concerns documentation.
.. seealso:: tutorial with a real world sample :doc:`examples <../tutorial/examples>`
Specialize variables
--------------------
Specialized variables
-----------------------
In a context of value presentation, tags can be very useful. They allow you to display variable values without knowing the list of variable paths.
In a context of value presentation, :term:`tagging <tag>` can be very useful. The :term:`tags <tag>` allow you to display variable values without knowing the list of variable paths.
.. glossary::
tag
A tag is just a name.
It add tags are a way to attach additional information or labels to variables.
Adding a tag is a way to attach additional information or label to variables.

2
docs/vac.rst
View file

@ -48,7 +48,7 @@ It is often necessary to recreate the same variables with the same constraints o
Variables as Code with Rougail
-----------------------------------
For this, we thought of a solution and came up with a concept of managing all our variables as a code called VaC (Variables as Code).
For this, we thought of a solution and came up with a concept of managing all our variables as a code called :term:`VaC (Variables as Code) <VaC>`.
Often when we talk about :term:`VaC` (or CaC) we think of the different environments (Development, Staging, Production).