adding titles corresponding to the git repo tutorial
This commit is contained in:
gwen
parent
043038526d
commit
f0018fcf93
1 changed files with 70 additions and 25 deletions
|
|
@ -6,8 +6,8 @@ Getting started
|
|||
We will learn how to:
|
||||
|
||||
- create a :term:`structure description file <structure file>`
|
||||
- add a :term:`structure file format version <structure file>`
|
||||
- add a :term:`variable` and set its :term:`value`
|
||||
- add a :term:`structure file <structure file>` format version in the structure file
|
||||
- add a :term:`variable` in the structure file and set its default :term:`value`
|
||||
|
||||
.. prerequisites:: Prerequisites
|
||||
|
||||
|
|
@ -36,13 +36,11 @@ Creating a structure file
|
|||
- First, we will create a :term:`structure file <structure file>`, so let's create a :file:`00-proxy.yml` file
|
||||
located in the :file:`firefox` subfolder.
|
||||
|
||||
.. type-along:: An empty structure file
|
||||
|
||||
This is an empty Rougail :term:`structure description file: <structure file>`
|
||||
|
||||
.. 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 the version number only
|
||||
:caption: An empty rougail structure file with only the YAML header and the version number
|
||||
:name: RougailStructVersion
|
||||
|
||||
..
|
||||
|
|
@ -51,16 +49,27 @@ This is an empty Rougail :term:`structure description file: <structure file>`
|
|||
|
||||
:tutorial:`Download this file from the rougail-tutorials git repository <src/tag/v1.1_000/firefox/00-proxy.yml>`
|
||||
|
||||
This `version` specification is just the rougail YAML's format version specification.
|
||||
By now, we have an empty structure file with the format specification in it.
|
||||
|
||||
Let's add our first variable
|
||||
------------------------------
|
||||
|
||||
.. note:: A variable is defined at a minimum by its name.
|
||||
.. type-along:: For those who follow the tutorial with the help of the git repository
|
||||
|
||||
A :term:`variable` in the :term:`structure description file <structure file>`
|
||||
Now you need to checkout the `v1.1_001` version::
|
||||
|
||||
git checkout v1.1_001
|
||||
|
||||
|
||||
- A variable is defined at a minimum by its name.
|
||||
- A :term:`variable` lives in the :term:`structure description file <structure file>`.
|
||||
|
||||
Here we define a variable named `proxy_mode`:
|
||||
|
||||
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_001/firefox/00-proxy.yml
|
||||
:language: yaml
|
||||
:caption: A Rougail structure file with only one variable
|
||||
:caption: A Rougail structure file with only one variable in it
|
||||
:name: RougailDictionaryFirstVariableName
|
||||
|
||||
..
|
||||
|
|
@ -69,14 +78,14 @@ A :term:`variable` in the :term:`structure description file <structure file>`
|
|||
|
||||
:tutorial:`Download this file from the rougail-tutorials git repository <src/tag/v1.1_001/firefox/00-proxy.yml>`
|
||||
|
||||
Let's run the Rougail CLI utility command:
|
||||
Let's run the Rougail CLI utility command in a terminal:
|
||||
|
||||
.. code-block:: text
|
||||
:class: terminal
|
||||
|
||||
rougail -m firefox/
|
||||
|
||||
we will actually have an error:
|
||||
Well, we notice that we have an error:
|
||||
|
||||
.. raw:: html
|
||||
:url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_001/config/01/output_ro.html
|
||||
|
|
@ -87,7 +96,7 @@ we will actually have an error:
|
|||
┣━━ The following variables are mandatory but have no value:
|
||||
┗━━ - proxy_mode
|
||||
|
||||
Because this variable is :term:`mandatory` and needs to be set **but** there's no value yet.
|
||||
It's because this first defined variable is :term:`mandatory` and needs to have a value set **but** there's no value yet.
|
||||
|
||||
We can therefore deduce the fact that:
|
||||
|
||||
|
|
@ -105,13 +114,25 @@ Rougail waits for the `proxy_mode` configuration option's value to be set.
|
|||
A variable is mandatory when a value is required, that is, `None` **is not** a possible value.
|
||||
It **must** have a defined value.
|
||||
|
||||
.. seealso:: To go further, have a look at the :tiramisu:`mandatory option <glossary.html#term-mandatory-option>` according to the definition of Tiramisu.
|
||||
.. seealso:: To go further, have a look at the :tiramisu:`mandatory option <glossary.html#term-mandatory-option>`
|
||||
according to the :xref:`Tiramisu <tiramisu>` underlyning consistency system.
|
||||
You will learn that it is actually possible to disable the mandatory property behavior,
|
||||
but you need to declare it explicitely.
|
||||
|
||||
Describe the variable
|
||||
-------------------------
|
||||
|
||||
Let's add a variable's description, which is not mandatory but which is a good practice:
|
||||
Let's add a variable's description, which is not mandatory but which is usually a good practice.
|
||||
|
||||
.. type-along:: For those who follow the tutorial with the help of the git repository
|
||||
|
||||
Now you need to checkout the `v1.1_002` version::
|
||||
|
||||
git checkout v1.1_002
|
||||
|
||||
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_002/firefox/00-proxy.yml
|
||||
:language: yaml
|
||||
:caption: A Rougail dictionnary file with a variable and a description
|
||||
:caption: A Rougail structure file with a variable and a description
|
||||
:name: RougailStructFirstVariableDescription
|
||||
|
||||
..
|
||||
|
|
@ -120,22 +141,45 @@ Let's add a variable's description, which is not mandatory but which is a good p
|
|||
|
||||
:tutorial:`Download this file from the rougail-tutorials git repository <src/tag/v1.1_002/firefox/00-proxy.yml>`
|
||||
|
||||
.. type-along:: how to set a value -- the default value
|
||||
You have two way to define a variable's description:
|
||||
|
||||
We need to set a value to this `proxy_mode` variable. A first way to do it is *to set a value by default*.
|
||||
- the verbose way:
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
proxy_mode:
|
||||
description: Configure Proxy Access to the Internet
|
||||
|
||||
|
||||
- or the compact way, using the "`#`" YAML notation:
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
proxy_mode: # Configure Proxy Access to the Internet
|
||||
|
||||
Set a default value
|
||||
---------------------
|
||||
|
||||
.. type-along:: For those who follow the tutorial with the help of the git repository
|
||||
|
||||
Now you need to checkout the `v1.1_003` version::
|
||||
|
||||
git checkout v1.1_003
|
||||
|
||||
We will learn different ways to set a value, the first way is setting a *default* value.
|
||||
|
||||
.. glossary::
|
||||
|
||||
default value
|
||||
|
||||
A default value is a variable value that is predefined, that is, this value is placed
|
||||
A default value is a variable value that is predefined, that's why this value is placed
|
||||
right in the structure file.
|
||||
|
||||
So let's define a variable with a description -- **and a default value**
|
||||
Let's add a default value to this `proxy_mode` variable.
|
||||
|
||||
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_003/firefox/00-proxy.yml
|
||||
:language: yaml
|
||||
:caption: A rougail dictionnary file with a default value for the variable
|
||||
:caption: A rougail structure file with a default value for the variable
|
||||
:name: RougailDictionaryVariableDefault
|
||||
|
||||
..
|
||||
|
|
@ -144,12 +188,13 @@ So let's define a variable with a description -- **and a default value**
|
|||
|
||||
:tutorial:`Download this file from the rougail-tutorials git repository <src/tag/v1.1_003/firefox/00-proxy.yml>`
|
||||
|
||||
.. type-along:: how to set a value -- the assignment
|
||||
.. admonition:: how to set a value -- the assignment
|
||||
|
||||
A default value has been set, great. Now how do I assign a value to a variable?
|
||||
A default value has been set, great. This raises a question about what a normal value is.
|
||||
|
||||
The different rougail roles and the default values
|
||||
------------------------------------------------------
|
||||
Now then how can I assign a normal value to a variable?
|
||||
|
||||
.. type-along:: The different rougail roles and the default values
|
||||
|
||||
So far we have only talked about the one that writes the :term:`structure files <structure file>`\ . It's *role* is called the integrator's role.
|
||||
|
||||
|
|
@ -256,7 +301,7 @@ In our firefox use case, the real type of the `proxy_mode` variable will be now
|
|||
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_004/firefox/00-proxy.yml
|
||||
:linenos:
|
||||
:language: yaml
|
||||
:caption: The real :file:`firefox/proxy.yml` Rougail dictionnary file with a choice type
|
||||
:caption: The real :file:`firefox/proxy.yml` Rougail structure file with a choice type
|
||||
:name: RougailDictionaryChoiceType
|
||||
|
||||
..
|
||||
|
|
@ -339,7 +384,7 @@ We have the list of the possible (authorized) values:
|
|||
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_004/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 structure file with a variable named `proxy_mode`, with a default value.
|
||||
|
||||
..
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue