diff --git a/docs/concepts.rst b/docs/concepts.rst index c5a0be5e2..8606755fe 100644 --- a/docs/concepts.rst +++ b/docs/concepts.rst @@ -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 `_ 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 `. 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