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

docs(concepts): concepts page proofreading

Browse source
This commit is contained in:
gwen 2026-06-04 11:26:47 +02:00
parent 26b5d8dd10
commit 9f28248903
1 changed files with 34 additions and 29 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

63
docs/concepts.rst
View file

@ -1,11 +1,11 @@
Abstract presentation
=========================
Rougail, a powerful, free/open-source configuration manager and language that combines declaration, data validation, and templating in a single, declarative syntax.
Rougail is a powerful, free/open-source configuration manager and language that combines declaration, data validation, and templating in a single, declarative syntax.
It will be useful to:
- define variables (the structure) easily and their constraintes
- define variables (the structure) easily and their constraints
- loads those variables
- generate variables documentation
- loads variables' values
@ -17,32 +17,34 @@ It will be useful to:
Why another configuration manager?
-------------------------------------
Using Rougail tansform end user consumer defined consistency rules into highly consistent business objects.
It's a configuration language designed to simplify and unify the way you define, validate, and generate configuration data.
Using Rougail tansforms end user consumer defined consistency rules into highly consistent business objects.
It's a configuration language designed to simplify and unify the way you define,
validate and generate configuration datas.
In other word, making it easier to manage complex configurations across multiple environments.
Rougail is:
- a commandline
- a CLI (command line interface) utility
- a `Python <https://www.python.org/>`_ library
- a description language
- a YAML based description language
What kind of configuration manager?
---------------------------------------------
At the time of the design of Rougail, there were structuring choices that defined the functioning of the tool.
At the time of the design of Rougail, there were structuring choices
that defined the functioning of the tool.
The steps in Rougail can be explain as follows:
The steps in Rougail can be explained as follows:
- loads the variable structured data
- loads the user data
- reads, validates, exports, document, ... the data
- loading the variable's structured data
- loading the user data
- reading, validating, exporting, documenting (and so on...) the data
Structured data
~~~~~~~~~~~~~~~~~
Structured data is also called Rougail format.
Structured data is also called the Rougail format.
.. glossary::
@ -56,7 +58,7 @@ Structured data is also called Rougail format.
It goes beyond traditional schema languages (like JSON Schema, OpenAPI, Cuelang)
by combinig type systems, powerful validation, consistency of the configuration and documentation.
Structured data are commonly place in structure file.
Structured data are commonly placed in :term:`structure files <structure file>`.
User data
~~~~~~~~~~
@ -84,15 +86,15 @@ Here a some user data examples:
Output
~~~~~~~
Structured and user data form a coherent configuration useful for different purpose.
Structured and user data form a coherent configuration useful for different purposes.
Output is here to define what kind of data we want.
And some output examples:
Here are some output examples:
- term:`Tiramisu` object
- extract JSON
- extract to Ansible inventory
- JSON extraction
- Ansible inventory extraction
- documentation
- custom table views
@ -115,7 +117,8 @@ It's clear that Rougail can be used in many contexts.
Here we'll define actor names. Obviously, these aren't the only possible actors.
We're just defining the actors within the Rougail context. Choice your own actor name if you wish to personnalize in your specific context.
We're just defining the actors within the Rougail context.
Choice your own actor name if you wish to personnalize in your specific context.
.. glossary::
@ -160,9 +163,10 @@ We're just defining the actors within the Rougail context. Choice your own actor
Variable lifetime
----------------------
Rougail's is a configuration language and data validation tool designed to simplify defining, validating, and generating structured configuration and data.
Rougail's a configuration language and data validation tool is designed
to simplify defining, validating, and generating structured configuration and data.
Rougail aims to define variables.
Rougail aims at defining variables.
Here we are talking about the variable lifetime.
@ -225,16 +229,17 @@ Variable mutability
Structured data
~~~~~~~~~~~~~~~~
When the integrator define the structure, variable are mutable.
When the integrator defines the structure, variables are mutable.
Even if the default behavior is to conflict when multiple declarations for the same variable.
Even if the default behavior is inconsistent, like when there is a conflict between multiple declarations for the same variable,
It's possible to explicitly allow to unifying (combined) multiple variables declarations.
it's possible to explicitly allow to unify (combine) multiple variables declarations.
User data
~~~~~~~~~~
It's no more possible to modifying variable definition.
At the user data level, it's no more possible to modify any variable definition.
Here we are just talking about variable's values.
Output
~~~~~~~
@ -268,14 +273,15 @@ Variable definition settings are immutable.
Value access
-------------
In the `structured data` step, there is no value, strictly speaking. It's a default value.
As other parameters, the default value is explicitly mutable.
In the :term:`structured data` step, there is no value, strictly speaking.
The values set are default values.
Like other parameters, the default value is explicitly mutable.
In the `user data` step, we can modify the values. That's precisely the purpose of this step.
The configuration is said to be in `read write` mode.
The configuration is said to be in :term:`read write mode`.
But at the `output` step, it is obviously no longer possible to modify the value.
The configuration is said to be in `read only` mode.
The configuration is said to be in :term:`read only mode`.
.. attention::
It is important not to confuse `value` and `calculated value`.
@ -317,7 +323,6 @@ Access control
Access control is achieved through `properties`.
.. glossary::
property