rougail/docs/gettingstarted.rst

Getting started
====================

.. _installation:

Installation
----------------

- Open a shell session

.. type-along:: Optional: install the Rougail library in a virtual environment

- install the virtual environment: `python -m"venv' .venv`
- activate it `./.venv/bin/activate` (or `.venv\Scripts\activate.exe` under windows)

.. type-along:: Rougail's library installation

You can use the `pip` python installer, here is the install command:

.. code-block:: text

    pip install rougail

What is a consistency handling system ?
------------------------------------------------

.. questions:: Rougail, Tiramisu: What is it all about?

    **Question**: OK, I have understood that the Rougail library allows me to take advantage of the :xref:`tiramisu` consistency handling library. But what is all this for? What is exactly a consistency handling system? And again, what is this :xref:`Tiramisu library <tiramisu library>` used for?

    **Answer**: Well, we will explain in details what this :xref:`tiramisu` library is and what Rougail is. 
    
    In (very) short: 

    - Rougail is the YAML consistency description of a :term:`context`\ 's situation
    - Tiramisu is the consistency engine linter

.. glossary::

   Tiramisu

        :xref:`tiramisu` is a consistency handling system that has initially been designed
        in the configuration management scope. Until now,
        this library is generally used to handle configuration options.

        It manages variables and group of variables. In the Tiramisu scope we call
        it *options* and *option descriptions*.

        Here is the :xref:`tiramisu documentation <tiramisu>`.

In the Rougail scope, we call it :term:`variables <variable>` and :term:`families <family>`.
In Rougail, the families and variables are located in the :term:`structure files <structure file>`.

The structure files
---------------------

.. glossary::

   structure file

       A structure file in the Rougail meaning is a YAML file that describes variables
       and their dependencies.
       There can be a lot of structure files located in many different folders.

       Rougail reads all the structure files and loads them into a single object
       that represents the whole :term:`context`.

.. figure:: images/schema.png
   :alt: The Rougail process
   :align: center

   The Rougail process from structure files to Tiramisu object

.. glossary:: 

   structured data
   
       We sometimes call 'structured datas' the datas that are in the structure files,
       as opposed to :term:`user datas <user data>`\ .
       For example when a value of a variable is defined in the structured datas, that is
       in a structured file, 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.

The variables
-----------------

Here is a :term:`structure file` example with only a variable **variable** named `proxy_mode`
A variable can be defined with no default value at all.

.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_011/firefox/00-proxy.yml
   :language: yaml
   :caption: A Rougail dictionnary file with a variable named `proxy_mode`, with a description.
   :name: RougailDictionaryFirstVariableDescription

..
    ---
    proxy_mode:
      description: 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_012/firefox/00-proxy.yml
   :language: yaml
   :caption: A Rougail dictionnary file with a variable named `proxy_mode`, with a default value.
   :name: RougailDictionaryFirstVariableDefault

..
    ---
    proxy_mode:
      description: Configure Proxy Access to the Internet
      default: No proxy

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`