doc(data documentation)

docs/concepts.rst

@@ -152,9 +152,9 @@ Choice your own actor name if you wish to personnalize in your specific context.
 
 Here is a reminder of the different steps:
 
-- the integrator defines the structure
+- the :term:`integrator` defines the structure
-- the operator sets the value
+- the :term:`operator` sets the value
-- the integrator and/or the operator use the output
+- the :term:`integrator` and/or the :term:`operator` use the output
 
 .. list-table::
    :header-rows: 1
@@ -229,7 +229,7 @@ Variable mutability
 Structured data
 ~~~~~~~~~~~~~~~~
 
-When the integrator defines the structure, variables are mutable.
+When the :term:`integrator` defines the structure, variables are mutable.
 
 Even if the default behavior is inconsistent, like when there is a conflict between multiple declarations for the same variable,
 
@@ -350,7 +350,7 @@ Hidden variable
 
 A `hidden` variable is a variable whose value cannot be modified by the operator.
 
-This could be an internal variable used by the integrator that is not supposed to change.
+This could be an internal variable used by the :term:`integrator` that is not supposed to change.
 
 Or a variable that only makes sense in a particular context. Therefore, this variable can be hidden and then unhidden depending on the context.
 

docs/conf.py

@@ -79,7 +79,7 @@ default_role = "code"
 html_theme = "sphinx_rtd_theme"
 pygments_style = 'sphinx'
 html_short_title = "Rougail"
-html_title = "Rougail documenation"
+html_title = "Rougail documentation"
 html_show_sourcelink = False
 html_show_sphinx = False
 html_show_copyright = True

docs/index.rst

@@ -48,8 +48,10 @@ Rougail
    :caption: Structured data
 
    structured_data
-   tutorial/index
+   structured_data/data_integrity
+   structured_data/documentation
    structured_data/index
+   tutorial/index
 
 .. toctree::
    :titlesonly:
@@ -70,7 +72,6 @@ Rougail
    :titlesonly:
    :caption: Developper notes
 
-   namespace
    release
    developer
    documentation

docs/namespace.rst

@@ -1,20 +0,0 @@
-Namespace
-=====================
-
-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.
-

docs/structured_data.rst

@@ -1,8 +1,8 @@
-The structure file
+The structure file and data
-=====================
+============================
 
-Definition
+What contains exactly a :term:`structure file`?
-------------
+-------------------------------------------------
 
 .. glossary::
 
@@ -15,6 +15,43 @@ Definition
        Rougail reads all the structure files and loads them into a single object
        that represents the whole :term:`context`.
 
+A :term:`structure file` is a YAML file whose structure is described in this documentation page.
+
+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.
+
+Separation of structures into namespaces
+----------------------------------------
+
+A namespace is a way to organize and group related variables under a unique name.
+
+It:
+
+- to avoid naming conflicts
+- permet logical grouping: related variables can be grouped together
+- scope control: namespaces limit the visibility of variable to the namespace itself
+
+By default there is no namespace.
+
+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 (the default 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.
+
 The header of a structure file
 -----------------------------------
 
@@ -23,12 +60,8 @@ A basic structure file is composed of:
 - a YAML 1.2 standard header
 - a version attribute
 
-.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_000/firefox/00-proxy.yml
+.. code-block:: yaml
-   :language: yaml
-   :caption: An empty Rougail structure file.
-   :name: RougailStructureFirstVariableDescription
 
-..
     %YAML 1.2
     ---
     version: 1.1
@@ -37,8 +70,8 @@ A basic structure file is composed of:
 The structure file processing
 ----------------------------------
 
-The structured files contain information that will be used by the consistency 
+The structured files contain information that will be used by the consistency handling system for structure validation. 
-handling system for structure validation. 
+This is what we call structured data write in Rougail format.
 
 .. figure:: images/schema.png
    :alt: The Rougail process
@@ -46,8 +79,8 @@ handling system for structure validation.
 
    The Rougail process from structure files to Tiramisu valition handler object
 
-The structured data
+A variable-first DSL
----------------------
+-----------------------
 
 All of the declaring variables and writing consistency is as simple as writing YAML.
 
@@ -55,14 +88,37 @@ We can declare variables and describe the relationships between variables in a d
 
 Once the structure files are loaded by Rougail, the Tiramisu configuration management tool can check the consistency of the variables between them.
 
-What contains exactly a :term:`structure file`?
+.. glossary::
--------------------------------------------------
 
-A :term:`structure file` is a YAML file whose structure is described in this documentation page.
+   DSL
 
-A structure file contains a set of variables, usable in your application, for example in a template
+       A DSL stands for **Domain-Specific Language**, it is a programming or markup language designed for a specific application domain.
-to generate configuration files.
+       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.
 
-:term:`Families <family>` and :term:`variables <variable>` can be defined in several structure files. These structure files are then aggregated.
+Rougail format (or :term:`structured data`) is a DSL (Domain-Specific Language) designed for describing variables and consistency.
 
-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>`
+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.
+
+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).
+
+There is an execption. That what we call the short-hand declaration.
+
+.. glossary::
+
+   Short-hand notation
+
+        Shorthand notation allows you to condense as much information as possible when creating a variable.
+        Generally, the declaration is done on a single line (or at most, a very small number of lines).
+
+        Of course, it's not possible to fully customize the variable with this notation.
+
+        Use shorthand notation whenever possible. This makes the file easier to read.

docs/structured_data/data_integrity.rst

@@ -1,45 +1,5 @@
-A variable-first DSL
-===============================
-
-.. glossary::
-
-   DSL
-
-       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.
-
-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.
-
-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).
-
-There is an execption. That what we call the short-hand declaration.
-
-.. glossary::
-
-   Short-hand notation
-
-        Shorthand notation allows you to condense as much information as possible when creating a variable.
-        Generally, the declaration is done on a single line (or at most, a very small number of lines).
-
-        Of course, it's not possible to fully customize the variable with this notation.
-
-        Use shorthand notation whenever possible. This makes the file easier to read.
-
 Data integrity
----------------
+===============
 
 Data integrity refers to the fact that data must be reliable and accurate throughout its lifecycle.
 
@@ -49,12 +9,16 @@ This means that the value must be:
 - appropriate to the overall context
 
 Data quality
-~~~~~~~~~~~~
+------------
 
 The values of the variables must be individually of good quality.
 
 Typing
-^^^^^^
+~~~~~~
+
+The typed variable concept refers to associating a data type with a variable, which defines what kind of values the variable can hold and what operations can be performed on it.
+
+Typed variables are a fundamental feature in Rougail. Type validation is the first and most important quality check.
 
 Strongly-typed
 ''''''''''''''
@@ -63,6 +27,8 @@ 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.
+
 .. For untyped user data (such as environment variables), the value type will be adapted during preprocessing.
 
 Dynamicly-typed
@@ -70,9 +36,9 @@ Dynamicly-typed
 
 During the structured data definition, the type is dynamic.
 
-That is to say, the integrator can change the type of the variable at any time.
+That is to say, the :term:`integrator` can change the type of the variable at any time.
 
-However, the operator who adapts the value does not have the possibility of redefining the type of the variable.
+However, the :term:`operator` who adapts the value does not have the possibility of redefining the type of the variable.
 
 .. seealso:: :doc:`the variable mutability <../concepts>`
 
@@ -84,6 +50,9 @@ 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`.
 
+Variables typing
+~~~~~~~~~~~~~~~~
+
 Standard types
 ''''''''''''''
 
@@ -125,9 +94,9 @@ The `null` type (or `None` in Python) does not exist in Rougail.
 
 All variables, regardless of their type, can be nullable (see the remarks on the list type below).
 
-Even if all types can accept this value, but by default, they do not.
+Even if all types can accept this value, by default, they do not.
 
-In reality, the variable is not accessible in `read-only` mode (which is the case during the output steps).
+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>`
@@ -137,22 +106,22 @@ 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 cannot contain values of multiple types.
+This means that all type could have multiple value by a list can only contain values of an uniq type.
 
-A multiple variable could be nullable. This means that `null` can be accepted as a value in the list (which is not permitted by default).
+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 (without is not permitted too 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>`
 
-Family
+Families typing
-''''''
+~~~~~~~~~~~~~~~
 
 The `mapping` type
-""""""""""""""""""
+''''''''''''''''''
 
 A mapping is a collection of key: value pairs.
 
-This is a YAML example:
+This is a JSON example:
 
 .. code-block:: json
 
@@ -168,7 +137,7 @@ Families manage the tree structure. It is possible to create subfamilies.
 .. seealso:: :doc:`the family documentation <family>`
 
 The dynamically built family
-""""""""""""""""""""""""""""
+''''''''''''''''''''''''''''
 
 A dynamically built family is a special family.
 
@@ -183,15 +152,16 @@ A dynamically built family is a special family.
 .. seealso:: :doc:`the dynamically built family documentation <family>`
 
 Homogeneous elements sequence
-"""""""""""""""""""""""""""""
+'''''''''''''''''''''''''''''
 
 .. glossary::
 
+   sequence
    homogeneous elements sequence
 
         A specific type of mapping, called a `sequence`, allows you to have a list of homogeneous objects.
 
-        For example, if I want to be able to create an unlimited number of users associated with a secret, I can't use lists; I need a list of objects.
+        For example, if I want to be able to create an unlimited number of users associated with a secret, you can't use lists; I need a list of objects.
 
         In JSON we will have:
 
@@ -209,7 +179,7 @@ Homogeneous elements sequence
            ]
 
 Validation
-^^^^^^^^^^
+~~~~~~~~~~
 
 Type validation is the first and most important check.
 But it is possible to add additional validations.
@@ -217,19 +187,19 @@ But it is possible to add additional validations.
 For example, one might want numbers, but only odd numbers.
 
 Overall coherence
-~~~~~~~~~~~~~~~~~
+-----------------
 
 An isolated variable can be considered to be of quality but become inconsistent depending on the context.
 
-Validation
+Consistency
-^^^^^^^^^^
+~~~~~~~~~~~
 
 For example, if a minimum value and then a maximum value are requested, the minimum must be less than the maximum.
 
 Overall consistency is initially managed by personality validators who 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.
 
@@ -239,18 +209,18 @@ There are two main types of access control:
 - Modes
 
 Properties
-""""""""""
+'''''''''''
 
 We already see the property access control.
 
-Remember, we talked about :doc:`the hidden and disabled variables`.
+Remember, we talked about :doc:`the hidden and disabled variables <../concepts>`.
 
 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?
 
 Mode
-""""
+''''
 
 By default, the mode is not configured. It is an optional feature.
 
@@ -263,8 +233,3 @@ Here is our classic 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.
-
-Documentation
--------------
-
-FIXME

docs/structured_data/documentation.rst

@@ -0,0 +1,69 @@
+Data documentation
+==================
+
+Documentation is an integral part of the definition of structured data.
+
+In a sense, we talk about `structured data` and not `schema` in Rougail because the documentation is an integral part of the variable definition.
+
+More broadly, considering the use of a VaC tool has the advantage of eliminating the need to manage documentation oneself.
+
+A lot of useful information for the :term:`operator` is naturally present when defining our variables. I'm thinking of its type, the constraints applied, its default value, the mode level, etc.
+
+But it is still necessary, as an :term:`integrator`, to guide the :term:`operator`.
+
+Describe the variable
+---------------------
+
+Describing the variable you create is not mandatory but it is highly recommended.
+Even a very well-chosen variable name does not replace a description.
+
+.. glossary::
+
+   description
+
+        A description allows you to describe the expected value(s) of a variable concisely and clearly.
+        It is designed to be clear precise and short.
+
+The description is used in different places in Rougail.
+
+Examples include:
+
+- warning/error message
+- different output
+
+Additional help to understand the variable
+------------------------------------------
+
+Help is a property that only concerns documentation.
+
+.. glossary::
+
+   help
+
+        A help helps to clarify any ambiguity about the variable’s purpose.
+        It can be long and detailed.
+
+.. seealso:: tutorial with a real world sample :doc:`help <../tutorial/examples>`
+
+Give examples of possible value
+-------------------------------
+
+Often a good example is more effective than a long text.
+
+Don't hesitate to guide the :term:`operator` with relevant examples.
+
+Examples is a property that only concerns documentation.
+
+.. seealso:: tutorial with a real world sample :doc:`examples <../tutorial/examples>`
+
+Specialize 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.
+
+.. glossary::
+
+   tag
+
+        A tag is just a name.
+        It add tags are a way to attach additional information or labels to variables.

docs/structured_data/family.rst

@@ -41,14 +41,14 @@ Parameters
 
        User information to understand the usefulness of the family.
 
-       .. seealso:: tutorial with a real world sample :doc:`description parameter <tutorial/family>`
+       .. seealso:: tutorial with a real world sample :doc:`description parameter <../tutorial/family>`
 
    * - **help**, **_help**
 
        `string`
      - Additional help associated with the family.
 
-       .. seealso:: tutorial with a real world sample :doc:`help parameter <tutorial/examples>` (the tutorial focuses on variable, but the principle is the same for a family)
+       .. seealso:: tutorial with a real world sample :doc:`help parameter <../tutorial/examples>` (the tutorial focuses on variable, but the principle is the same for a family)
 
    * - **mode**, **_mode**
 
@@ -63,7 +63,7 @@ Parameters
 
        **Default value**: The default mode of a family is the smallest mode of the parent families, child variables, or child families that are contained in that family.
 
-       .. seealso:: tutorial with a real world sample :doc:`mode parameter <tutorial/mode>` (the tutorial focuses on variable, but the principle is the same for a family)
+       .. seealso:: tutorial with a real world sample :doc:`mode parameter <../tutorial/mode>` (the tutorial focuses on variable, but the principle is the same for a family)
 
    * - **type**, **_type**
 
@@ -85,7 +85,7 @@ Parameters
 
        **Default value**: `false`
 
-       .. seealso:: tutorial with a real world sample :doc:`hidden parameter <tutorial/properties>`
+       .. seealso:: tutorial with a real world sample :doc:`hidden parameter <../tutorial/properties>`
 
    * - **disabled**, **_disabled**
 
@@ -98,7 +98,7 @@ Parameters
 
        **Default value**: `false`
 
-       .. seealso:: tutorial with a real world sample :doc:`disabled parameter <tutorial/properties>`
+       .. seealso:: tutorial with a real world sample :doc:`disabled parameter <../tutorial/properties>`
 
    * - **dynamic**, **_dynamic**
 
@@ -128,7 +128,7 @@ Parameters
 .. note::
 
    If a subfamily or a subvariable already has the name of a parameter it is possible to use the "_<parameter>" name.
-   You can have a look at the tutorial with a real world sample :doc:`of parameter with "_" <tutorial/underscore_parameter>`.
+   You can have a look at the tutorial with a real world sample :doc:`of parameter with "_" <../tutorial/underscore_parameter>`.
 
 Short-hand declaration
 ----------------------------
@@ -185,8 +185,8 @@ Here is a simple example:
 
    You can have a look at the tutorial with a real world sample:
 
-   - :doc:`family <tutorial/family>`
+   - :doc:`family <../tutorial/family>`
-   - :doc:`help parameter <tutorial/examples>` (the tutorial focuses on variable, but the principle is the same for a family)
+   - :doc:`help parameter <../tutorial/examples>` (the tutorial focuses on variable, but the principle is the same for a family)
 
 A dynamically built family
 -----------------------------
@@ -221,7 +221,7 @@ This will dynamically create two families:
 
 .. seealso::
 
-   You can have a look at the tutorial with a real world sample :doc:`dynamically built family <tutorial/dynfam>`
+   You can have a look at the tutorial with a real world sample :doc:`dynamically built family <../tutorial/dynfam>`
 
 Sequence of homogeneous elements
 ---------------------------------------
@@ -266,7 +266,7 @@ It's what we call a Sequence of homogeneous elements.
 
 .. seealso::
 
-   You can have a look at the tutorial with a real world sample :doc:`Sequence of homogeneous elements <tutorial/sequence>`
+   You can have a look at the tutorial with a real world sample :doc:`Sequence of homogeneous elements <../tutorial/sequence>`
 
 A custom type family
 ----------------------
@@ -278,4 +278,4 @@ This custom type family can be used as many times as desired and customized as y
 
 .. seealso::
 
-   You can have a look at the tutorial with a real world sample :doc:`family custom type <tutorial/family>`
+   You can have a look at the tutorial with a real world sample :doc:`family custom type <../tutorial/family>`

docs/structured_data/index.rst

@@ -8,7 +8,6 @@ Common informations on structured data
    :titlesonly:
    :caption: Structured data
 
-   concepts
    naming_convention
    variable
    family

docs/tags.rst

@@ -1,26 +0,0 @@
-:orphan:
-
-The `tag` parameter's variable
-================================
-
-
-Here is an example:
-
-.. code-block:: yaml
-
-    %YAML 1.2
-    ---
-    version: 1.1
-
-    internal_domain:
-      description: Server domaine name
-      type: domainname
-      tags:
-        - internal
-
-    external_domain:
-      description: Domain name to access to this server for Internet
-      type: domainname
-      tags:
-        - external
-    ...

docs/tutorial/examples.rst

@@ -242,15 +242,15 @@ In the same way, this help `"Connections to localhost, 127.0.0.1/8 and ::1 are n
 .. type-along:: The difference between the `description` parameter and the `help` parameter
 
 The help section serves as supplementary documentation regarding the description parameter.
-Please do not mix the `description` parameter and the `help` parameter's variable usage.
+Please do not mix the :term:`description` parameter and the :term:`help` parameter's variable usage.
 
-A `description` allows you to describe the expected value(s) of a variable concisely and clearly.
+A :term:`description` allows you to describe the expected value(s) of a variable concisely and clearly.
 It is designed to be clear precise and short, much like the help of some 
 command-line utility when you type the command with the `--help` or `-h` option.
 
-A `help` helps to clarify any ambiguity about the variable’s purpose. It can be long and detailed.
+A :term:`help` helps to clarify any ambiguity about the variable’s purpose. It can be long and detailed.
 
-We can set `help` attribute to a variable or to a family.
+We can set :term:`help` attribute to a variable or to a family.
 
 .. keypoints:: Key points