diff --git a/docs/concepts.rst b/docs/concepts.rst index 8605286c8..a4fd13a0a 100644 --- a/docs/concepts.rst +++ b/docs/concepts.rst @@ -1,7 +1,15 @@ Abstract presentation ========================= -Rougail is a powerful, free/open-source configuration manager and language that combines declaration, data validation, and templating in a single, declarative syntax. +Rougail is a robust and powerful, free/open-source configuration manager. + +Rougail is: + +- a CLI (command line interface) utility +- a `Python `_ library +- a YAML based description language + +The language combines declaration, data validation, and templating in a single, declarative syntax. It will be useful to: @@ -23,11 +31,14 @@ validate and generate configuration datas. In other word, making it easier to manage complex configurations across multiple environments. -Rougail is: +You might tell me that other configuration management tools do the same thing. And that's partly true. -- a CLI (command line interface) utility -- a `Python `_ library -- a YAML based description language +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. + +Your configuration is therefore consistent, easily accessible, and modifiable. + +Not to mention the always up-to-date documentation and the information you provide to your users regarding changes to variables. What kind of configuration manager? --------------------------------------------- @@ -101,13 +112,13 @@ Here are some output examples: .. list-table:: :header-rows: 1 - * - Step + * - **Step** - * - Structured data + * - **Structured data** - * - User data + * - **User data** - * - Output + * - **Output** What kind of actor? --------------------- @@ -148,16 +159,16 @@ Here is a reminder of the different steps: .. list-table:: :header-rows: 1 - * - Step + * - **Step** - Actor - * - Structured data + * - **Structured data** - Integrator - * - User data + * - **User data** - Operator - * - Output + * - **Output** - - Operator - Integrator @@ -173,52 +184,38 @@ Here we are talking about the variable lifetime. The variable’s lifetime is the period between its creation and its destruction. -The lifecycle of a variable includes the generic stages (like, in the Python language): +The lifecycle of a variable includes the generic stages (like, in the C language): -.. list-table:: - :header-rows: 1 - - * - Creation - - Assignment - - Reading - - Destruction - - * - Variables are assigned a name and a type - - The variable's value is modified - - The variable's value is used - - The variable terminates upon the destruction of the object +- Creation: variables are assigned a name and a type +- Initialization: they are assigned their first value +- Assignment: the variable's value is modified +- Reading: the variable's value is used +- Destruction: the variable terminates upon the destruction of the object But other concepts are included in the lifecycle: -.. list-table:: - :header-rows: 1 - - * - Permission - - Documentation - - Specialization - - * - Properties describe access constraints - - Informations for variable documentation like description or help. Those informations are used to build documentation, changelog, ... - - Define usage, selection,... - +- Permission: properties describe access constraints +- Documentation: informations for variable documentation like description or help. Those informations are used to build documentation, changelog, ... +- Specialization: define usage, selection,... .. list-table:: :header-rows: 1 - * - Step + * - **Step** - Actor - Lifetime - * - Structured data + * - **Structured data** - Integrator - - Creation + - - Creation + - Initialization - * - User data + * - **User data** - Operator - - Assignment - Permission - * - Output + * - **Output** - - Operator - Integrator - - Reading @@ -252,24 +249,24 @@ Variable definition settings are immutable. .. list-table:: :header-rows: 1 - * - Step + * - **Step** - Actor - Lifetime - Mutability - * - Structured data + * - **Structured data** - Integrator - - Creation - - initialization + - Initialization - Mutable - * - User data + * - **User data** - Operator - - Assignment - Permission - Immutable - * - Output + * - **Output** - - Operator - Integrator - - Reading @@ -299,27 +296,27 @@ The configuration is said to be in :term:`read only mode`. .. list-table:: :header-rows: 1 - * - Step + * - **Step** - Actor - Lifetime - Mutability - Value - * - Structured data + * - **Structured data** - Integrator - - Creation - - initialization + - Initialization - Mutable - Mutable default value - * - User data + * - **User data** - Operator - - Assignment - Permission - Immutable - Read write - * - Output + * - **Output** - - Operator - Integrator - - Reading @@ -367,22 +364,22 @@ This property is generally used dynamically to remove access to the variable dep .. list-table:: :header-rows: 1 - * - Step + * - **Step** - Actor - Lifetime - Mutability - Value - Access control - * - Structured data + * - **Structured data** - Integrator - - Creation - - initialization + - Initialization - Mutable - Mutable default value - N/A - * - User data + * - **User data** - Operator - - Assignment - Permission @@ -391,7 +388,7 @@ This property is generally used dynamically to remove access to the variable dep - - hidden - disabled - * - Output + * - **Output** - - Operator - Integrator - - Reading diff --git a/docs/index.rst b/docs/index.rst index 063ed18c9..87103ba16 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -12,7 +12,7 @@ Rougail 2 check.rst:56: WARNING: term not in glossary: 'follower' 4 family.rst:25: WARNING: label non défini: 'convention on variable names' - 5 structfile.rst:89: WARNING: term not in glossary: 'variable_namespace' + 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' @@ -25,7 +25,7 @@ Rougail .. todo:: créer les documents suivants: 1 rougail/docs/family.rst:102: WARNING: unknown document: 'tutorial/mode' - 3 rougail/docs/structfile.rst:89: WARNING: term not in glossary: 'variable_namespace' + 3 rougail/docs/structureddata.rst:89: WARNING: term not in glossary: 'variable_namespace' 4 rougail/docs/variable.rst:163: WARNING: unknown document: 'tutorial/mode' 5 rougail/docs/variable.rst:235: WARNING: unknown document: 'tutorial/validators' 6 rougail/docs/variable.rst:263: WARNING: unknown document: 'tutorial/autosave' @@ -44,30 +44,20 @@ Rougail :caption: What is it all about concepts + +.. toctree:: + :titlesonly: + :caption: Structured data + + structured_data tutorial/index + structured_data/index .. toctree:: :titlesonly: - :caption: Structure files + :caption: User data - structfile - naming_convention - -.. toctree:: - :titlesonly: - :caption: Variables and families - - variable - family - fill - Value checks - condition - -.. toctree:: - :titlesonly: - :caption: The values -- the user datas - - user_datas/index + user_data/index .. toctree:: :titlesonly: @@ -82,6 +72,7 @@ Rougail :titlesonly: :caption: Developper notes + namespace release developer documentation @@ -90,7 +81,6 @@ Rougail :hidden: install - naming_convention .. rubric:: Index page diff --git a/docs/namespace.rst b/docs/namespace.rst new file mode 100644 index 000000000..903da8bce --- /dev/null +++ b/docs/namespace.rst @@ -0,0 +1,20 @@ +Nmaespace +===================== + +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 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. + diff --git a/docs/structfile.rst b/docs/structured_data.rst similarity index 50% rename from docs/structfile.rst rename to docs/structured_data.rst index 9ed1a193b..7e92fb682 100644 --- a/docs/structfile.rst +++ b/docs/structured_data.rst @@ -1,4 +1,4 @@ -The structure files +The structure file ===================== Definition @@ -49,24 +49,9 @@ handling system for structure validation. The structured data --------------------- -.. glossary:: +All of the declaring variables and writing consistency is as simple as writing YAML. - structured data - - We sometimes call "structured datas" the datas that are defined the structure, - as opposed to :term:`user datas `\ . - For example when a value of a variable is defined in the structured datas - the assigned value's status is that the variable's value is a default value. - If the assigned value of the variable is defined in a user data file, - it is an user assigned value. - -We'll see later on some examples of default values and user assigned values. - -The main advantage of all of this that declaring variables and writing consistency is as simple -as writing YAML. With Rougail it is not necessary to write :term:`Tiramisu` code any more. -It simplifies a lot of things. - -And rather than writing :term:`Tiramisu` code, we can declare variables and describe the relationships between variables in a declarative style (that is, in a YAML file). +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. @@ -75,26 +60,9 @@ What contains exactly a :term:`structure file`? A :term:`structure file` is a YAML file whose structure is described in this documentation page. -A structure file contains a set of variables loaded into :term:`Tiramisu`, usable in your application, for example in a template +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. If you want to see the contents of a structure file, you can have a look at the :ref:`tutorial with a real world sample. ` - -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 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. diff --git a/docs/fill.rst b/docs/structured_data/calculation.rst similarity index 100% rename from docs/fill.rst rename to docs/structured_data/calculation.rst diff --git a/docs/condition.rst b/docs/structured_data/condition.rst similarity index 100% rename from docs/condition.rst rename to docs/structured_data/condition.rst diff --git a/docs/family.rst b/docs/structured_data/family.rst similarity index 100% rename from docs/family.rst rename to docs/structured_data/family.rst diff --git a/docs/structured_data/index.rst b/docs/structured_data/index.rst new file mode 100644 index 000000000..f74a017c5 --- /dev/null +++ b/docs/structured_data/index.rst @@ -0,0 +1,16 @@ +Rougail format +=============== + +Common informations on structured data + + +.. toctree:: + :titlesonly: + :caption: Structured data + + naming_convention + variable + family + calculation + Value validations + condition diff --git a/docs/naming_convention.rst b/docs/structured_data/naming_convention.rst similarity index 100% rename from docs/naming_convention.rst rename to docs/structured_data/naming_convention.rst diff --git a/docs/check.rst b/docs/structured_data/validation.rst similarity index 100% rename from docs/check.rst rename to docs/structured_data/validation.rst diff --git a/docs/variable.rst b/docs/structured_data/variable.rst similarity index 93% rename from docs/variable.rst rename to docs/structured_data/variable.rst index 83b43c840..5c208adcf 100644 --- a/docs/variable.rst +++ b/docs/structured_data/variable.rst @@ -52,14 +52,14 @@ Parameters User information to understand the usefulness of the variable. - .. seealso:: tutorial with a real world sample :doc:`description parameter ` + .. seealso:: tutorial with a real world sample :doc:`description parameter <../tutorial/preliminary>` * - **help** `string` - Additional help associated with the variable. - .. seealso:: tutorial with a real world sample :doc:`help parameter ` + .. seealso:: tutorial with a real world sample :doc:`help parameter <../tutorial/examples>` * - **mode** @@ -78,7 +78,7 @@ Parameters - if the variable is not in a family, the variable will have a medium mode by default - a :term:`mandatory` variable without default value (calculate or not) will have the smaller mode - .. seealso:: tutorial with a real world sample :doc:`mode parameter ` + .. seealso:: tutorial with a real world sample :doc:`mode parameter <../tutorial/mode>` * - **tags** @@ -97,7 +97,7 @@ Parameters `list` - List of examples to illustrate possible values for a variable - .. seealso:: tutorial with a real world sample :doc:`examples parameter ` + .. seealso:: tutorial with a real world sample :doc:`examples parameter <../tutorial/examples>` * - **test** @@ -113,7 +113,7 @@ Parameters See the list of available type below. - .. seealso:: tutorial with a real world sample :doc:`type parameter ` + .. seealso:: tutorial with a real world sample :doc:`type parameter <../tutorial/types>` * - **params** @@ -122,7 +122,7 @@ Parameters See the list of available parameters for each type below. - .. seealso:: tutorial with a real world sample :doc:`params parameter ` + .. seealso:: tutorial with a real world sample :doc:`params parameter <../tutorial/types>` * - **multi** @@ -141,7 +141,7 @@ Parameters - multi_min_length: maximum number of expected values for a multiple variable - multi_max_length: minimum number of expected values for a minimum variable - .. seealso:: tutorial with a real world sample :doc:`multi parameter ` + .. seealso:: tutorial with a real world sample :doc:`multi parameter <../tutorial/multiple>` * - **validators** @@ -150,7 +150,7 @@ Parameters The value of the variable will be considered invalid if the Jinja template return an error. - .. seealso:: tutorial with a real world sample :doc:`validators parameter ` + .. seealso:: tutorial with a real world sample :doc:`validators parameter <../tutorial/validators>` * - **default** - Default value(s) of the variable. @@ -159,7 +159,7 @@ Parameters For a non :term:`leading` :term:`multiple ` variable, the first value defined in the list will also be the default value proposed if a new value is added to this variable. - .. seealso:: tutorial with a real world sample :doc:`default parameter ` + .. seealso:: tutorial with a real world sample :doc:`default parameter <../tutorial/preliminary>` * - **secret_manager** - The variable use a secret manager to get value @@ -178,7 +178,7 @@ Parameters **Default value**: `false` - .. seealso:: tutorial with a real world sample :doc:`auto_save parameter ` + .. seealso:: tutorial with a real world sample :doc:`auto_save parameter <../tutorial/autosave>` * - **mandatory** @@ -191,7 +191,7 @@ Parameters **Default value**: `true` - .. seealso:: tutorial with a real world sample :doc:`mandatory parameter ` + .. seealso:: tutorial with a real world sample :doc:`mandatory parameter <../tutorial/nullable>` * - **empty** @@ -226,7 +226,7 @@ Parameters **Default value**: `false` - .. seealso:: tutorial with a real world sample :doc:`hidden parameter ` (the tutorial focuses on family, but the principle is the same for a variable) + .. seealso:: tutorial with a real world sample :doc:`hidden parameter <../tutorial/properties>` (the tutorial focuses on family, but the principle is the same for a variable) * - **disabled** @@ -241,7 +241,7 @@ Parameters **Default value**: `false` - .. seealso:: tutorial with a real world sample :doc:`disabled parameter ` (the tutorial focuses on family, but the principle is the same for a variable) + .. seealso:: tutorial with a real world sample :doc:`disabled parameter <../tutorial/properties>` (the tutorial focuses on family, but the principle is the same for a variable) * - **frozen** @@ -407,7 +407,7 @@ Primitive Types * - boolean - A boolean, if no value is defined the default value of this variable will be `true`, the variable will also be :term:`mandatory` by default - .. seealso:: tutorial with a real world sample :doc:`boolean type variable ` + .. seealso:: tutorial with a real world sample :doc:`boolean type variable <../tutorial/types>` - - `true` @@ -428,7 +428,7 @@ Specialized type * - secret - a secret (like a password, a private key, etc.) - .. seealso:: tutorial with a real world sample :doc:`secret type variable ` + .. seealso:: tutorial with a real world sample :doc:`secret type variable <../tutorial/redefine>` - `min_len`: minimum characters length for the secret (unlimited by default) `max_len`: maximum characters length for the secret (unlimited by default) @@ -458,7 +458,7 @@ Specialized type * - unix_user - a user in the Unix meaning - .. seealso:: tutorial with a real world sample :doc:`unix type variable ` + .. seealso:: tutorial with a real world sample :doc:`unix type variable <../tutorial/redefine>` - - test @@ -504,7 +504,7 @@ Specialized type `test_existence`: the domain name must exist (`false` by default) - .. seealso:: tutorial with a real world sample :doc:`domainname type variable ` or :doc:`a more complet domainname type variable ` + .. seealso:: tutorial with a real world sample :doc:`domainname type variable <../tutorial/types>` or :doc:`a more complet domainname type variable <../tutorial/multiple>` - `rougail.example` * - web_address @@ -531,7 +531,7 @@ Specialized type `allow_private`: private ports (greater than 49152) are allowed (`false` by default) - .. seealso:: tutorial with a real world sample :doc:`web_address type variable ` + .. seealso:: tutorial with a real world sample :doc:`web_address type variable <../tutorial/webaddress>` - http://rougail.example * - port @@ -546,7 +546,7 @@ Specialized type `allow_private`: private ports (greater than 49152) are allowed (`false` by default) - .. seealso:: tutorial with a real world sample :doc:`port type variable ` + .. seealso:: tutorial with a real world sample :doc:`port type variable <../tutorial/types>` - 8080 * - mac @@ -562,14 +562,14 @@ Specialized type * - choice - available choices - .. seealso:: tutorial with a real world sample :doc:`choice type variable ` + .. seealso:: tutorial with a real world sample :doc:`choice type variable <../tutorial/choice>` - - * - regexp - Validation with a regular expressions - .. seealso:: tutorial with a real world sample :doc:`regexp type variable ` + .. seealso:: tutorial with a real world sample :doc:`regexp type variable <../tutorial/regexp>` - - r"^#(?:[0-9a-f]{3}){1,2}$" @@ -580,14 +580,14 @@ If the `type` parameter is not set, Rougail has to define a logical type to vali - if `choices` or `regexp` parameter is set, Rougail will set the `choice` or `regexp` type -.. seealso:: tutorial with a real world sample :doc:`choice deducted type ` or :doc:`regexp deducted type ` +.. seealso:: tutorial with a real world sample :doc:`choice deducted type <../tutorial/choice>` or :doc:`regexp deducted type <../tutorial/regexp>` - if a default value is define, Rougail will infers default value type and set a primitive type to the variable -.. seealso:: tutorial with a real world sample :doc:`type inference ` +.. seealso:: tutorial with a real world sample :doc:`type inference <../tutorial/types>` - if a variable calculation is define as default value, Rougail copy the type -.. seealso:: tutorial with a real world sample :doc:`type copying ` +.. seealso:: tutorial with a real world sample :doc:`type copying <../tutorial/calculated>` - the default type is `string` diff --git a/docs/user_datas/bitwarden.rst b/docs/user_data/bitwarden.rst similarity index 100% rename from docs/user_datas/bitwarden.rst rename to docs/user_data/bitwarden.rst diff --git a/docs/user_datas/commandline.rst b/docs/user_data/commandline.rst similarity index 100% rename from docs/user_datas/commandline.rst rename to docs/user_data/commandline.rst diff --git a/docs/user_datas/environment.rst b/docs/user_data/environment.rst similarity index 100% rename from docs/user_datas/environment.rst rename to docs/user_data/environment.rst diff --git a/docs/user_datas/index.rst b/docs/user_data/index.rst similarity index 83% rename from docs/user_datas/index.rst rename to docs/user_data/index.rst index 0512aa36f..12f2715c3 100644 --- a/docs/user_datas/index.rst +++ b/docs/user_data/index.rst @@ -1,5 +1,5 @@ -`Rougail`'s user datas description -================================== +User data description +====================== Rougail is a collections of subproject to adjust functionalities to your needs. diff --git a/docs/user_datas/questionary.rst b/docs/user_data/questionary.rst similarity index 100% rename from docs/user_datas/questionary.rst rename to docs/user_data/questionary.rst diff --git a/docs/user_datas/yaml.rst b/docs/user_data/yaml.rst similarity index 100% rename from docs/user_datas/yaml.rst rename to docs/user_data/yaml.rst