getting started -> hello world to tutorial
This commit is contained in:
gwen
parent
98f788ee9b
commit
543d54144b
2 changed files with 106 additions and 21 deletions
|
|
@ -60,12 +60,12 @@ 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
|
||||
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.
|
||||
:caption: An empty Rougail dictionnary file. It's a YAML format.
|
||||
:name: RougailDictionaryEmptyFile
|
||||
|
||||
..
|
||||
|
|
@ -98,7 +98,7 @@ 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.
|
||||
:caption: A Rougail dictionnary file with a variable named `proxy_mode`. It's the Rougail YAML dictionary format.
|
||||
:name: RougailDictionaryFirstVariable
|
||||
|
||||
..
|
||||
|
|
@ -112,7 +112,7 @@ 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.
|
||||
:caption: A Rougail dictionnary file with a variable named `proxy_mode`, with a description.
|
||||
:name: RougailDictionaryFirstVariableDescription
|
||||
|
||||
..
|
||||
|
|
@ -124,7 +124,7 @@ 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.
|
||||
:caption: A Rougail dictionnary file with a variable named `proxy_mode`, with a default value.
|
||||
:name: RougailDictionaryFirstVariableDefault
|
||||
|
||||
..
|
||||
|
|
@ -147,3 +147,32 @@ 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
|
||||
|
||||
|
|
|
|||
|
|
@ -6,26 +6,82 @@ Preliminaries
|
|||
We will learn how to:
|
||||
|
||||
- create a Rougail :term:`structure description file <dictionary>`
|
||||
- define a Rougail format version
|
||||
- define a Rougail :term:`structure description file <dictionary>` format version
|
||||
- define a Rougail :term:`variable` and set its :term:`value`
|
||||
|
||||
.. type-along:: Basics
|
||||
.. prerequisites:: Prerequisites
|
||||
|
||||
Dictionary
|
||||
-------------
|
||||
We assume that Rougail's library is :ref:`already installed <installation>` on your computer (or in a virtual environment).
|
||||
|
||||
Define a Rougail :term:`structure description file <dictionary>`
|
||||
.. exercise:: The folder structure
|
||||
|
||||
https://forge.cloud.silique.fr/stove/rougail-tutorials/src/commit/v1.1_000/firefox/00-proxy.yml
|
||||
Here is the tree structure we want to have::
|
||||
|
||||
workplace
|
||||
├── firefox
|
||||
│ ├── dictionary.yml
|
||||
|
||||
Here is an empty Rougail dictionnary <RougailDictionaryEmptyFile>`
|
||||
- Let's make a :file:`workplace` directory, with a :file:`dict` subfolder.
|
||||
- First, we wil make a :term:`dictionary`, so let's make the :file:`dictionary.yml` file
|
||||
which is located in the :file:`firefox` subfolder.
|
||||
- Then we will run this command
|
||||
|
||||
- define a variable and its default value
|
||||
.. code-block:: shell
|
||||
|
||||
:ref:`Here is a first Rougail variable in a Rougail dictionnary <RougailDictionaryFirstVariable>`
|
||||
foo@bar:~$ rougail -v 1.1 -m firefox/
|
||||
|
||||
which actually outputs an error:
|
||||
|
||||
.. raw:: html
|
||||
:url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_010/config/01/output_ro.html
|
||||
|
||||
..
|
||||
🛑 ERRORS
|
||||
┣━━ The following variables are mandatory but have no value:
|
||||
┗━━ - proxy_mode
|
||||
|
||||
Because this variable is :term:`mandatory` and needs to be set.
|
||||
|
||||
FIXME : ce dico doit être mis en haut
|
||||
|
||||
.. type-along:: a default dictionary
|
||||
|
||||
An empty structure description file
|
||||
|
||||
The dictionary
|
||||
----------------
|
||||
|
||||
This is an empty Rougail dictionnary
|
||||
|
||||
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_000/firefox/00-proxy.yml
|
||||
:language: yaml
|
||||
:caption: An empty rougail dictionnary file with only the version
|
||||
:name: RougailDictionaryEmptyFile
|
||||
|
||||
..
|
||||
---
|
||||
version: 1.1
|
||||
|
||||
.. type-along:: a dictionary with a variable
|
||||
|
||||
Let's define a Rougail :term:`structure description file <dictionary>` with something defined in it.
|
||||
|
||||
Defining a variable and its default value
|
||||
----------------------------------------------
|
||||
|
||||
This is a first Rougail variable in a Rougail dictionnary.
|
||||
|
||||
.. 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 only one variable
|
||||
:name: RougailDictionaryFirstVariableName
|
||||
|
||||
..
|
||||
---
|
||||
proxy_mode:
|
||||
|
||||
This is a Rougail variable in a Rougail dictionnary, we define a variable with a description of it.
|
||||
|
||||
- define a variable with a description
|
||||
|
||||
:ref:`Here is a Rougail variable with a description <RougailDictionaryFirstVariableDescription>`
|
||||
|
||||
|
|
@ -89,7 +145,7 @@ So, if :
|
|||
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_010/firefox/00-proxy.yml
|
||||
:linenos:
|
||||
:language: yaml
|
||||
:caption: The :file:`firefox/00-proxy.yaml` rougail structure file, with no default value set.
|
||||
:caption: The :file:`firefox/00-proxy.yaml` Rougail structure file, with no default value set.
|
||||
:name: RougailDictionaryNoDefault
|
||||
|
||||
..
|
||||
|
|
@ -99,7 +155,7 @@ So, if :
|
|||
Then the rougail CLI will output an error :
|
||||
|
||||
.. code-block:: shell
|
||||
:caption: A rougail Command Line Utility call with the :file:`config/01/config.yaml` rougail dictionnary file
|
||||
:caption: A rougail Command Line Utility call with the :file:`config/01/config.yaml` Rougail dictionnary file
|
||||
|
||||
foo@bar:~$ rougail -v 1.1 -m firefox -u file -ff config/01/config.yaml
|
||||
|
||||
|
|
@ -127,7 +183,7 @@ Rougail waits for the `proxy_mode` configuration option's value to be set.
|
|||
Variable's type
|
||||
-----------------
|
||||
|
||||
If the `type` attribute is not set, rougail infers a `string` type for the `proxy_mode` configuration option variable type as defined in the structure file.
|
||||
If the `type` attribute is not set, Rougail infers a `string` type for the `proxy_mode` configuration option variable type as defined in the structure file.
|
||||
|
||||
If the operator sets an option value for example with the `number` type, like this:
|
||||
|
||||
|
|
@ -138,13 +194,13 @@ If the operator sets an option value for example with the `number` type, like th
|
|||
description: Configure Proxy Access to the Internet
|
||||
type: number
|
||||
|
||||
Then rougail will expect a `int` or a `float` as a value for the `example_var` variable.
|
||||
Then Rougail will expect a `int` or a `float` as a value for the `example_var` variable.
|
||||
In our firefox use case, the real type of the `proxy_mode` variable is a `choice` type:
|
||||
|
||||
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_013/firefox/00-proxy.yml
|
||||
:linenos:
|
||||
:language: yaml
|
||||
:caption: The :file:`firefox/00-proxy.yml` rougail dictionnary file, with a default value set.
|
||||
:caption: The :file:`firefox/00-proxy.yml` Rougail dictionnary file, with a default value set.
|
||||
:name: RougailDictionaryChoiceTypeWitheDefault
|
||||
|
||||
..
|
||||
|
|
@ -222,7 +278,7 @@ We have the list of the possible (authorized) values:
|
|||
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_013/firefox/00-proxy.yml
|
||||
:linenos:
|
||||
:language: yaml
|
||||
:caption: A rougail dictionnary file with a variable named `proxy_mode`, with a default value.
|
||||
:caption: A Rougail dictionnary file with a variable named `proxy_mode`, with a default value.
|
||||
|
||||
..
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue