diff --git a/docs/gettingstarted.rst b/docs/gettingstarted.rst index 6349be04b..8cbd0b9dc 100644 --- a/docs/gettingstarted.rst +++ b/docs/gettingstarted.rst @@ -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 ` 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 + diff --git a/docs/tutorial/preliminary.rst b/docs/tutorial/preliminary.rst index 60ed1c6ce..ae283d60c 100644 --- a/docs/tutorial/preliminary.rst +++ b/docs/tutorial/preliminary.rst @@ -6,26 +6,82 @@ Preliminaries We will learn how to: - create a Rougail :term:`structure description file ` - - define a Rougail format version + - define a Rougail :term:`structure description file ` 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 ` on your computer (or in a virtual environment). -Define a Rougail :term:`structure description file ` +.. 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 ` +- 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 ` + 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 ` 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 ` @@ -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. ..