diff --git a/docs/gettingstarted.rst b/docs/gettingstarted.rst index f05173621..08a74a712 100644 --- a/docs/gettingstarted.rst +++ b/docs/gettingstarted.rst @@ -97,17 +97,34 @@ The variables Here is a :term:`dictionary` example with a variable into it: -.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_003/config/03/config.yaml +.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_003/firefox/00-proxy.yml :linenos: :language: yaml :caption: A rougail dictionnary file with a variable named `proxy_mode`. It's the Rougail YAML dictionary format. :name: RougailDictionaryFirstVariable -:download:`source file ` +:download:`source file ` -Here we declare a **variable** named `proxy_mode` with a variable :term:`default value`. +Here we declare a **variable** named `proxy_mode` without a :term:`default value`. A variable can be defined with no default value at all. +Here is the same variable with a description label: + +.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_004/firefox/00-proxy.yml + :linenos: + :language: yaml + :caption: A rougail dictionnary file with a variable named `proxy_mode`, with a description. + :name: RougailDictionaryFirstVariableDescription + +The same with a default value: + + +.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_005/firefox/00-proxy.yml + :linenos: + :language: yaml + :caption: A rougail dictionnary file with a variable named `proxy_mode`, with a default value. + :name: RougailDictionaryFirstVariableDefault + variable A variable is a declaration unit that represents a business domain metaphor, @@ -115,6 +132,10 @@ variable in a application, but a variable represents something more that a configuration option. It provides a business domain specific representation unit. +.. todo:: définir une variable avec une description, un type, l'inférence de type, + les notations condensées, + une family sans variable doit avoir un type: family, + .. note:: Dictionaries can just define a list of variables, but we will see that we can specify a lot more. We can define variables **and** their relations, **and** the relations between them. diff --git a/docs/index.rst b/docs/index.rst index 94c438fee..38054c2b3 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -8,6 +8,8 @@ Rougail =========== +.. todolist:: + .. image:: images/logo.png - is a `delicious cooked dish `_ from the Mauritius and Reunion Islands, @@ -32,7 +34,7 @@ Explained differently, Rougail allows you to easily implement an integration of .. toctree:: :titlesonly: :caption: The library - + library configuration @@ -42,7 +44,7 @@ Explained differently, Rougail allows you to easily implement an integration of dictionary dict_convention - + .. toctree:: :titlesonly: :caption: The variables @@ -52,11 +54,11 @@ Explained differently, Rougail allows you to easily implement an integration of fill Value checks condition - + .. toctree:: :titlesonly: :caption: Notes - + developer .. rubric:: Index page diff --git a/docs/tutorial/images/integrator.png b/docs/tutorial/images/integrator.png new file mode 100644 index 000000000..a1b869901 Binary files /dev/null and b/docs/tutorial/images/integrator.png differ diff --git a/docs/tutorial/images/operator.png b/docs/tutorial/images/operator.png new file mode 100644 index 000000000..a45b096f2 Binary files /dev/null and b/docs/tutorial/images/operator.png differ diff --git a/docs/tutorial/preliminary.rst b/docs/tutorial/preliminary.rst index d45d96688..fd6379585 100644 --- a/docs/tutorial/preliminary.rst +++ b/docs/tutorial/preliminary.rst @@ -5,8 +5,60 @@ Preliminaries You need to know how to: - - manipulate a rougail :term:`dictionary` - - use a rougail format version - - use the rougail command line + - create a Rougail :term:`dictionary` + - define a Rougail format version + - define a Rougail :term:`variable` + +.. type-along:: Workshop + + - define a Rougail :term:`dictionary` + + :ref:`Here is an empty Rougail dictionnary ` + + - define a variable and its default value + + :ref:`Here is a first Rougail variable in a Rougail dictionnary ` + + - define a variable with a description + + :ref:`Here is a Rougail variable with a description ` + + - define a variable with a description and a default value + + :ref:`Here is a Rougail variable with a description ` + + +The integrator role +---------------------- + +.. glossary:: + + integrator + + An integrator in the Rougail logic is the person who writes the dictionaries. + He has the responsibilité of the integration process, that is, + defines the variables and the relationship between them, the variables that are allowed + (or not) to be set, and so on. His responsabilites are the **structuration** and the **consistency** + of the variables. + + .. image:: images/integrator.png + +.. important:: Note that there is a strong consistency, it means that the validation is done across + the entire structure, not only with a schema (type) validation system. + +The operator role +--------------------- + +.. glossary:: + + operator + + An operator ih the Rougail logic is the person who gives values to the pre-defined variables, + his responsabilities are to set variable values correctly. + + The :term:`user values`, that is the values that have been set by the operator, are validated + by the dictionary structure. + + .. image:: images/operator.png + -- :ref:`Here is an empty rougail dictionnary `