rougail/docs/gettingstarted.rst

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

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

.. questions:: Question

    "OK, I have understood that the Rougail stuff enables me to take advantage of :xref:`tiramisu`.
    But what is all this for?
    What is exactly a consistency handling system?
    And again, what is this :xref:`tiramisu` library used for?"

    **Answer**: Well, now we explain what this :xref:`tiramisu` library is, and how we are using it.

.. glossary::

   Tiramisu

        :xref:`tiramisu` is a consistency handling system that has initially been designed
        in the configuration management scope. To put it more simply,
        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 library`.

In the Rougail scope, we call it :term:`variable`\ s and :term:`families`.
In Rougail, the families and variables are located in the :term:`structure files <dictionaries>` (the term "dictionary" is also used as a synonym).

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

.. glossary::

   structure file
   dictionary
   dictionaries

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

       Rougail reads all the dictionaries and loads them into a single object
       that handles the variables consistency.

.. image:: images/schema.png

The main advantage is 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 YAML structure files format
------------------------------------

We need to learn first the specifics of the YAML dictionaries file format in Rougail, as well as some templating concepts.

Here is an empty Rougail dictionary YAML file

.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_000/firefox/00-proxy.yml
   :linenos:
   :language: yaml
   :caption: An empty Rougail dictionnary file. It's a YAML format.
   :name: RougailDictionaryEmptyFile

..
    ---
    version: 1.1


:download:`source file <https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_000/firefox/00-proxy.yml>`

You can see that there is just a `version` specification.

.. glossary::

   version

       The version is here a Rougail YAML dictionary version format.
       It is set in the beginning of a YAML dictionary, or globaly in the Rougail settings
       for example from the command line

.. note:: You can set the format in the Rougail command line tool like this:

       .. code-block:: bash

            foo@bar:~$ rougail -v 1.1

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

Here is a :term:`structure file <dictionary>` example with a variable into it:

.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_010/firefox/00-proxy.yml
   :language: yaml
   :caption: A Rougail dictionnary file with a variable named `proxy_mode`. It's the Rougail YAML dictionary format.
   :name: RougailDictionaryFirstVariable

..
    ---
    proxy_mode:

Here we declare a **variable** named `proxy_mode` without a 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_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 subfamily.

.. _installation:

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

You just have to type this in your preferred terminal:

.. code-block:: text

    pip install rougail
    
a better way to install the Rougail library in to do this in a virtual environment:

.. code-block:: text

    python -m"venv' .venv

And, under linux or Mac:

.. code-block:: shell

    ./.venv/bin/activate 

or, under windows:

.. code-block:: text 

    .venv\Scripts\activate.exe