stove/rougail
3
0
Fork 0
Code Issues 10 Pull requests 1 Projects Releases Wiki Activity

getting started update

Browse source
This commit is contained in:
gwen 2025-02-20 11:35:55 +01:00
parent 10a25b0cfe
commit 2d39fe8bad
1 changed files with 46 additions and 81 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

127
docs/gettingstarted.rst
View file

@ -1,15 +1,42 @@
Getting started Getting started
==================== ====================
.. _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
What is a consistency handling system ? What is a consistency handling system ?
------------------------------------------------ ------------------------------------------------
.. questions:: Question .. questions:: Question
"OK, I have understood that the Rougail stuff enables me to take advantage of :xref:`tiramisu`. **Question**: OK, I have understood that the Rougail library enables me to take advantage of the :xref:`tiramisu` library. But what is all this for? What is exactly a consistency handling system? And again, what is this :xref:`tiramisu library` used for?
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. **Answer**: Well, now we explain what this :xref:`tiramisu` library is, and how we are using it.
@ -24,7 +51,7 @@ What is a consistency handling system ?
It manages variables and group of variables. In the Tiramisu scope we call It manages variables and group of variables. In the Tiramisu scope we call
it *options* and *option descriptions*. it *options* and *option descriptions*.
Here is the :xref:`tiramisu library`. Here is the :xref:`tiramisu documentation <tiramisu>`.
In the Rougail scope, we call it :term:`variable`\ s and :term:`families`. 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 <structure file>`. In Rougail, the families and variables are located in the :term:`structure files <structure file>`.
@ -53,61 +80,12 @@ And rather than writing :term:`Tiramisu` code, we can declare variables and desc
Once the structure files are loaded by Rougail, the Tiramisu configuration management tool can check the consistency of the variables between them. 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 structure 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 structure file version format.
It is set in the beginning of a YAML structure file, 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
rougail -v 1.1
The variables The variables
----------------- -----------------
Here is a :term:`structure file` example with a variable into it: Here is a :term:`structure file` example with only a variable **variable** named `proxy_mode`
.. 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 structure file 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. 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 .. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_011/firefox/00-proxy.yml
:language: yaml :language: yaml
:caption: A Rougail dictionnary file with a variable named `proxy_mode`, with a description. :caption: A Rougail dictionnary file with a variable named `proxy_mode`, with a description.
@ -143,34 +121,21 @@ Families of variables
family family
A :term:`family` is simply a container of variables and subfamily. A :term:`family` is simply a container of variables and/ore some subfamilies.
.. _installation: Here how a YAML structure file with a family looks like:
Installation .. code-block:: yaml
---------------- :caption: A :file:`hello.yml` structure sample file
You just have to type this in your preferred terminal: ---
version: '1.1'
world:
description: Hello world family container
name:
description: Somebody to say hello
default: rougail
.. code-block:: text Here, we have a family named `world`.
This family contains a variable named `name`
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