doc: various changes

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 <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
+But Rougail adds interesting features in variable management that other projects don't have.
-- a `Python <https://www.python.org/>`_ library
+I am of course referring to the documentation management included directly in the configuration manager.
-- a YAML based description language
+
+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::
+- Creation: variables are assigned a name and a type
-   :header-rows: 1
+- Initialization: they are assigned their first value
-
+- Assignment: the variable's value is modified
-   * - Creation
+- Reading: the variable's value is used
-     - Assignment
+- Destruction: the variable terminates upon the destruction of the object
-     - 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
 
 But other concepts are included in the lifecycle:
 
-.. list-table::
+- Permission: properties describe access constraints
-   :header-rows: 1
+- Documentation: informations for variable documentation like description or help. Those informations are used to build documentation, changelog, ...
-
+- Specialization: define usage, selection,...
-   * - 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,...
-
 
 .. 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

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
+   user_data/index
-   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
 
 .. 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
 

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 <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,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 can declare variables and describe the relationships between variables in a declarative style (that is, in a YAML file).
-   
-       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).
 
 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.

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 <validation>
+   condition

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 <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`

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.