From 2d39fe8bad5327355611dc1013af04bf26634c78 Mon Sep 17 00:00:00 2001 From: gwen Date: Thu, 20 Feb 2025 11:35:55 +0100 Subject: [PATCH] getting started update --- docs/gettingstarted.rst | 127 +++++++++++++++------------------------- 1 file changed, 46 insertions(+), 81 deletions(-) diff --git a/docs/gettingstarted.rst b/docs/gettingstarted.rst index 2c05609fd..9a90a7dbc 100644 --- a/docs/gettingstarted.rst +++ b/docs/gettingstarted.rst @@ -1,15 +1,42 @@ 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 ? ------------------------------------------------ .. 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?" + **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? **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 *options* and *option descriptions*. - Here is the :xref:`tiramisu library`. + Here is the :xref:`tiramisu documentation `. 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 `. @@ -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. -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 ` - -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 ----------------- -Here is a :term:`structure file` 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 structure file format. - :name: RougailDictionaryFirstVariable - -.. - --- - proxy_mode: - -Here we declare a **variable** named `proxy_mode` without a default value. +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. -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. @@ -143,34 +121,21 @@ Families of variables 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 - - 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 +Here, we have a family named `world`. +This family contains a variable named `name`