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

doc: various changes

Browse source
This commit is contained in:
egarette@silique.fr 2026-06-04 20:43:51 +02:00
parent 9dfdf908f0
commit 484a4ad92c
17 changed files with 132 additions and 141 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

111
docs/concepts.rst
View file

@ -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 <https://www.python.org/>`_ 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 <https://www.python.org/>`_ 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

34
docs/index.rst
View file

@ -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 <check>
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

20
docs/namespace.rst Normal file
View file

@ -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 <variable_namespace>` parameter of the :doc:`configuration <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 <configuration>`.
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.

40
docs/structfile.rst → docs/structured_data.rst
View file

@ -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 <user data>`\ .
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 <family>` and :term:`variables <variable>` 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. <tutorial>`
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 <variable_namespace>` parameter of the :doc:`configuration <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 <configuration>`.
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.

0
docs/fill.rst → docs/structured_data/calculation.rst
View file

0
docs/condition.rst → docs/structured_data/condition.rst
View file

0
docs/family.rst → docs/structured_data/family.rst
View file

16
docs/structured_data/index.rst Normal file
View file

@ -0,0 +1,16 @@
Rougail format
===============
Common informations on structured data
.. toctree::
:titlesonly:
:caption: Structured data
naming_convention
variable
family
calculation
Value validations <validation>
condition

0
docs/naming_convention.rst → docs/structured_data/naming_convention.rst
View file

0
docs/check.rst → docs/structured_data/validation.rst
View file

48
docs/variable.rst → docs/structured_data/variable.rst
View file

@ -52,14 +52,14 @@ Parameters
User information to understand the usefulness of the variable.
.. seealso:: tutorial with a real world sample :doc:`description parameter <tutorial/preliminary>`
.. 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 <tutorial/examples>`
.. 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 <tutorial/mode>`
.. 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 <tutorial/examples>`
.. 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 <tutorial/types>`
.. 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 <tutorial/types>`
.. 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 <tutorial/multiple>`
.. 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 <tutorial/validators>`
.. 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 <multi>` 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 <tutorial/preliminary>`
.. 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 <tutorial/autosave>`
.. 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 <tutorial/nullable>`
.. 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 <tutorial/properties>` (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 <tutorial/properties>` (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 <tutorial/types>`
.. 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 <tutorial/redefine>`
.. 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 <tutorial/redefine>`
.. 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 <tutorial/types>` or :doc:`a more complet domainname type variable <tutorial/multiple>`
.. 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 <tutorial/webaddress>`
.. 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 <tutorial/types>`
.. 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 <tutorial/choice>`
.. 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 <tutorial/regexp>`
.. 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 <tutorial/choice>` or :doc:`regexp deducted type <tutorial/regexp>`
.. 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 <tutorial/types>`
.. 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 <tutorial/calculated>`
.. seealso:: tutorial with a real world sample :doc:`type copying <../tutorial/calculated>`
- the default type is `string`

0
docs/user_datas/bitwarden.rst → docs/user_data/bitwarden.rst
View file

0
docs/user_datas/commandline.rst → docs/user_data/commandline.rst
View file

0
docs/user_datas/environment.rst → docs/user_data/environment.rst
View file

4
docs/user_datas/index.rst → docs/user_data/index.rst
View file

@ -1,5 +1,5 @@
`Rougail`'s user datas description
==================================
User data description
======================
Rougail is a collections of subproject to adjust functionalities to your needs.

0
docs/user_datas/questionary.rst → docs/user_data/questionary.rst
View file

0
docs/user_datas/yaml.rst → docs/user_data/yaml.rst
View file