docs(proofreading): doc release preparation

docs/cli.rst

@@ -1,5 +1,3 @@
-:orphan:
-
 The Rougail Command Line Interface
 ========================================
 
@@ -10,7 +8,6 @@ Les help
 
     rougail -u yaml -h
 
-
 Standard usage 
 -----------------
 
@@ -142,6 +139,7 @@ Le output doc
 ::
 
     rougail -m structure.yml -o doc --doc.output_format github > README.md 
+
 ::
 
       doc:
@@ -162,8 +160,6 @@ Le output doc
       --doc.no-document_a_type
 
 
-
-
 Le formatter
 ----------------
 

docs/configuration.rst

@@ -40,7 +40,7 @@ The functions file
 
 The file which contains the custom functions is managed in the `functions_file` key and has the default value `/srv/rougail/functions.py`. This key can contain a list if there are several files.
 
-.. important:: Functions must return a value, even if the variable being calculated is a :term:`multiple` variable. If the function can return a multiple value (a list), you must put the name of the function in the `multi_functions` key.
+.. important:: Functions must return a value, even if the variable being calculated is a :term:`multiple <multi>` variable. If the function can return a multiple value (a list), you must put the name of the function in the `multi_functions` key.
 
 The `auto_freeze` variable
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

docs/family.rst

@@ -77,14 +77,14 @@ Parameters
 
        User information to understand the usefulness of the family.
 
-       .. seealso:: tutorial with a real world sample :ref:`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 :ref:`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**
 
@@ -99,7 +99,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 :ref:`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**
 
@@ -121,7 +121,7 @@ Parameters
 
        **Default value**: `false`
 
-       .. seealso:: tutorial with a real world sample :ref:`hidden parameter <tutorial/properties>`
+       .. seealso:: tutorial with a real world sample :doc:`hidden parameter <tutorial/properties>`
 
    * - **disabled**, **_disabled**
 
@@ -134,7 +134,7 @@ Parameters
 
        **Default value**: `false`
 
-       .. seealso:: tutorial with a real world sample :ref:`disabled parameter <tutorial/properties>`
+       .. seealso:: tutorial with a real world sample :doc:`disabled parameter <tutorial/properties>`
 
    * - **dynamic**, **_dynamic**
 
@@ -164,7 +164,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 :ref:`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>`.
 
 A family
 ---------
@@ -187,8 +187,8 @@ Here is a simple example:
 
    You can have a look at the tutorial with a real world sample:
 
-   - :ref:`family <tutorial/family>`
+   - :doc:`family <tutorial/family>`
-   - :ref:`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
 -----------------------------
@@ -225,7 +225,7 @@ This will dynamically create two families:
 
 .. seealso::
 
-   You can have a look at the tutorial with a real world sample :ref:`dynamically built family <tutorial/dynfam>`
+   You can have a look at the tutorial with a real world sample :doc:`dynamically built family <tutorial/dynfam>`
 
 Similar object sequence
 -------------------------
@@ -270,7 +270,7 @@ It's what we call a sequence of similar object.
 
 .. seealso::
 
-   You can have a look at the tutorial with a real world sample :ref:`similar object sequence <tutorial/sequence>`
+   You can have a look at the tutorial with a real world sample :doc:`similar object sequence <tutorial/sequence>`
 
 A custom type family
 ----------------------
@@ -282,4 +282,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 :ref:`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/gettingstarted.rst

@@ -1,82 +0,0 @@
-:orphan:
-
-The variables
------------------
-
-Here is a :term:`structure file` example with only a variable **variable** named `proxy_mode`
-A variable can be defined without other informations.
-
-.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_001/firefox/00-proxy.yml
-   :language: yaml
-   :caption: A Rougail structure file with a variable named `proxy_mode`, with a description.
-   :name: RougailStructureFirstVariable
-
-..
-    %YAML 1.2
-    ---
-    version: 1.1
-
-    proxy_mode:
-    ...
-
-But it's better to describe this variable:
-
-.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_001/firefox/00-proxy.yml
-   :language: yaml
-   :caption: A Rougail structure file with a variable named `proxy_mode`, with a description.
-   :name: RougailStructureFirstVariableWithDescription
-
-..
-    %YAML 1.2
-    ---
-    version: 1.1
-
-    proxy_mode:  # Configure Proxy Access to the Internet
-    ...
-
-
-The same with a default value:
-
-.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_003/firefox/00-proxy.yml
-   :language: yaml
-   :caption: A Rougail structure file with a variable named `proxy_mode`, with a default value.
-   :name: RougailStructureFirstVariableDefault
-
-..
-    %YAML 1.2
-    ---
-    version: 1.1
-    
-    proxy_mode: No proxy  # Configure Proxy Access to the Internet
-    ...
-
-variable
-
-    A :term:`variable` is a declaration unit that represents a business domain metaphor,
-    the most common example is that a variable that represents a configuration option
-    in a application, but a variable represents something more that a configuration option.
-    It provides a business domain specific representation unit.
-
-Families of variables
---------------------------
-
-family
-
-    A :term:`family` is simply a container of variables and/ore some subfamilies.
-
-Here how a YAML structure file with a family looks like:
-
-.. code-block:: yaml
-   :caption: A :file:`hello.yml` structure sample file
-
-    ---
-    version: '1.1'
-    world:
-      description: Hello world family container
-      name:
-        description: Somebody to say hello
-        default: rougail
-
-Here, we have a family named `world`.
-This family contains a variable named `name`
-

docs/index.rst

@@ -8,11 +8,10 @@
 Rougail
 ===========
 
-.. todo:: définir les termes suivants
+.. todo:: définir les termes suivants:
 
       1 check.rst:9: WARNING: term not in glossary: 'validator'                       
       2 check.rst:56: WARNING: term not in glossary: 'follower'
-      3 configuration.rst:43: WARNING: term not in glossary: 'multiple'
       4 family.rst:25: WARNING: label non défini: 'convention on variable names'
       5 structfile.rst:89: WARNING: term not in glossary: 'variable_namespace'
       6 tutorial/tutorial.rst:437: WARNING: term not in glossary: 'leadership'
@@ -23,8 +22,18 @@ Rougail
       11 variable.rst:154: WARNING: term not in glossary: 'required'
       12 variable.rst:156: WARNING: term not in glossary: 'leader'
       13 variable.rst:156: WARNING: term not in glossary: 'follower'
-      14 variable.rst:186: WARNING: term not in glossary: 'multiple'
+
-      15 variable.rst:186: WARNING: term not in glossary: 'multiple'
+
+.. todo:: créer les documents suivants:
+
+      1 rougail/docs/family.rst:102: WARNING: unknown document: 'tutorial/mode'                                                                                                                   
+      2 rougail/docs/family.rst:273: WARNING: unknown document: 'tutorial/sequence'
+      3 rougail/docs/structfile.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'
+
+
 
 
 .. image:: images/logo.png
@@ -42,14 +51,14 @@ Rougail
 
 .. toctree::
    :titlesonly:
-   :caption: The structured files
+   :caption: Structure files
 
    structfile
    naming_convention
 
 .. toctree::
    :titlesonly:
-   :caption: The options
+   :caption: Variables and families
 
    variable
    family
@@ -60,20 +69,21 @@ Rougail
 
 .. toctree::
    :titlesonly:
-   :caption: Load values from user datas
+   :caption: The values -- the user datas
 
    user_datas/index
 
 .. toctree::
    :titlesonly:
-   :caption: The library
+   :caption: The library and the tools
 
-   library/index
    configuration
+   cli
+   library/index
    
 .. toctree::
    :titlesonly:
-   :caption: Notes
+   :caption: Developper notes
 
    developer
    documentation

docs/tags.rst

@@ -1,5 +1,7 @@
-The variable tags
+The `tag` parameter's variable
-==================
+================================
+
+FIXME: a étoffer
 
 Here is an example:
 

docs/tutorial/family.rst

@@ -273,4 +273,4 @@ Let's recap about the user data. We can see in this Rougail CLI output that:
 
 .. seealso::
 
-   Full documentation about :ref:`family <family>`
+   The full documentation about a :term:`family`.

docs/tutorial/index.rst

@@ -61,4 +61,5 @@ Let's dive into this **configuration options validation** use case.
    multiple
    examples
    practice1
+   underscore_parameter
    whatsnext

docs/variable.rst

@@ -134,14 +134,14 @@ Parameters
 
        User information to understand the usefulness of the variable.
 
-       .. seealso:: tutorial with a real world sample :ref:`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 :ref:`help parameter <tutorial/examples>`
+       .. seealso:: tutorial with a real world sample :doc:`help parameter <tutorial/examples>`
 
    * - **mode**
 
@@ -160,7 +160,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 :ref:`mode parameter <tutorial/mode>`
+       .. seealso:: tutorial with a real world sample :doc:`mode parameter <tutorial/mode>`
 
    * - **tags**
 
@@ -179,7 +179,7 @@ Parameters
        `list`
      - List of examples to illustrate possible values for a variable
 
-       .. seealso:: tutorial with a real world sample :ref:`examples parameter <tutorial/examples>`
+       .. seealso:: tutorial with a real world sample :doc:`examples parameter <tutorial/examples>`
 
    * - **test**
 
@@ -195,7 +195,7 @@ Parameters
 
        See the list of available type below.
 
-       .. seealso:: tutorial with a real world sample :ref:`type parameter <tutorial/types>`
+       .. seealso:: tutorial with a real world sample :doc:`type parameter <tutorial/types>`
 
    * - **params**
 
@@ -204,14 +204,15 @@ Parameters
 
        See the list of available parameters for each type below.
 
-       .. seealso:: tutorial with a real world sample :ref:`params parameter <tutorial/types>`
+       .. seealso:: tutorial with a real world sample :doc:`params parameter <tutorial/types>`
 
    * - **multi**
 
        `boolean`
+
      - The value of the variable is a list.
 
-       **Default value**: mostly `false, but there is special cases:
+       **Default value**: mostly `false`, but there is special cases:
 
        - the default value is a list
        - a variable with a variable :term:`multiple <multi>` has default value
@@ -222,7 +223,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 :ref:`multi parameter <tutorial/multiple>`
+       .. seealso:: tutorial with a real world sample :doc:`multi parameter <tutorial/multiple>`
 
    * - **validators**
 
@@ -231,7 +232,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 :ref:`validators parameter <tutorial/validators>`
+       .. seealso:: tutorial with a real world sample :doc:`validators parameter <tutorial/validators>`
 
    * - **default**
      - Default value(s) of the variable.
@@ -240,7 +241,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 :ref:`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
@@ -259,7 +260,7 @@ Parameters
 
        **Default value**: `false`
 
-       .. seealso:: tutorial with a real world sample :ref:`auto_save parameter <tutorial/autosave>`
+       .. seealso:: tutorial with a real world sample :doc:`auto_save parameter <tutorial/autosave>`
 
    * - **mandatory**
 
@@ -272,7 +273,7 @@ Parameters
 
        **Default value**: `true`
 
-       .. seealso:: tutorial with a real world sample :ref:`mandatory parameter <tutorial/nullable>`
+       .. seealso:: tutorial with a real world sample :doc:`mandatory parameter <tutorial/nullable>`
 
    * - **empty**
 
@@ -307,7 +308,7 @@ Parameters
 
        **Default value**: `false`
 
-       .. seealso:: tutorial with a real world sample :ref:`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**
 
@@ -322,7 +323,7 @@ Parameters
 
        **Default value**: `false`
 
-       .. seealso:: tutorial with a real world sample :ref:`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**