rougail/docs/gettingstarted.rst
egarette@silique.fr bdd56d31c8 feat: suffixes in dynamic family should be a jinja function (#5)
Co-authored-by: Emmanuel Garette <egarette@silique.fr>
Co-authored-by: gwen <gwenaelremond@free.fr>
Reviewed-on: #5
Co-authored-by: egarette@silique.fr <egarette@silique.fr>
Co-committed-by: egarette@silique.fr <egarette@silique.fr>
2024-10-14 14:14:00 +02:00

191 lines
5.6 KiB
ReStructuredText
Raw Blame History

This file contains invisible Unicode characters

This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

.. |Tiramisu| replace:: Tiramisu
.. _tiramisu: https://forge.cloud.silique.fr/stove/tiramisu
Getting started
====================
What is a consistency handling system ?
------------------------------------------------
.. questions:: Question: "OK, I have understood that the Rougail stuff enables me to take advantage of |Tiramisu|. But what is all this for? What is exactly a consistency handling system? And again, what is this |Tiramisu| library used for?"
*Answer*: Well, let's explain what |Tiramisu| is and how we are using the |Tiramisu| library.
.. glossary::
Tiramisu
|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*.
In the Rougail scope, we call it :term:`variable`\ s and :term:`families`.
In Rougail, the families and variables are located in the :term:`dictionaries`.
And this is what we are going to explain in this page.
The dictionaries
---------------------
.. glossary::
dictionary
dictionaries
A dictionary 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 mode (that is, in a YAML file).
Once the dictionaries are loaded by Rougail, we find all the power of the :term:`Tiramisu` configuration management tool.
The YAML dictionaries format
-----------------------------
Before getting started with Rougail we need to learn the specifics of the YAML dictionaries file format (as well as some templating concepts).
.. FIXME parler de jinja https://jinja.palletsprojects.com
Here is a :term:`dictionary` example:
.. code-block:: yaml
:linenos:
---
version: '1.1'
proxy:
description: Configure Proxy Access to the Internet
type: family
Line 3, we declare a **variable** named `proxy` with his `description` line 4 and his `type` line 5.
The variables
-----------------
variable
Here is a second definition of a :term:`variable`: it 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.
.. 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 consistency between them.
In the next step, we will explain through a tutorial how to construct a list of variables.
Families of variables
--------------------------
.. glossary::
family
families
A family of variables is simply a collection of variables that refer to
the same business model category. It's just a variables container.
Think of it as a container as well as a namespace.
A "hello world" with Rougail
------------------------------
We're gonna make the simplest possible example.
.. prerequisites:: Prerequisites
We assume that Rougail's library is installed on your computer (or in a virtual environment).
.. exercise:: Let's make a Hello world
Here is the tree structure we want to have::
workplace
├── dict
   │   ├── hello.yml
   └── hello.py
- Let's make a :file:`workplace` directory, with a :file:`dict` subfolder.
- First, we need a :term:`dictionary`, so let's make the :file:`hello.yml` file
which is located in the :file:`dict` subfolder, with the following content:
.. code-block:: yaml
:caption: The `hello.yaml` file
---
version: '1.1'
hello:
default: world
- Then we make a :file:`hello.py` in our root :file:`workplace` directory:
.. code-block:: python
:caption: The :file:`hello.py` file
from rougail import Rougail, RougailConfig
RougailConfig['dictionaries_dir'] = ['dict']
rougail = Rougail()
config = rougail.get_config()
print(config.value.get())
.. demo:: Let's run the :file:`hello.py` script
We launch the script:
.. code-block:: bash
python hello.py
And we obtain the following result:
.. code-block:: python
{'rougail.hello': 'world'}
**Congratulations ! You have successfully completed your first Rougail script.**
A "Hello, <name> " sample with a family
------------------------------------------
Let's continuing on our "Hello world" theme and add a :term:`family` container.
.. code-block:: yaml
:caption: the :file:`hello.yml` file
:linenos:
---
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`
Again, let's validate this YAML file against Rougail's API:
.. code-block:: bash
python hello.py
We then have the output:
.. code-block:: python
{'rougail.world.name': 'rougail'}