diff --git a/docs/library/user_datas.rst b/docs/library/user_datas.rst index b7889d42e..47e112560 100644 --- a/docs/library/user_datas.rst +++ b/docs/library/user_datas.rst @@ -81,9 +81,7 @@ Here is the script which is load user data from the YAML file: rougail = Rougail() config = rougail.run() - user_datas = RougailUserDataYaml( - config, - ).run() + user_datas = RougailUserDataYaml(config).run() rougail.user_datas(user_datas) print(config.value.get()) @@ -135,8 +133,9 @@ Environment variables We can define use data from environment variables. The environment name is a "prefix" (ROUGAIL by default) with "_" and variable name in uppercase format. For example: -- my_variable has ROUGAIL_MY_VARIABLE as a environment variable name -- my_family.my_variable has ROUGAIL_MY_FAMILY.MY_VARIABLE as a environment variable name + +- `my_variable` has `ROUGAIL_MY_VARIABLE` as a environment variable name +- `my_family.my_variable` has `ROUGAIL_MY_FAMILY.MY_VARIABLE` as a environment variable name Some shell doesn't allow dot in environment file. In this case use the command "env". @@ -156,9 +155,7 @@ Here is the script: rougail = Rougail() config = rougail.run() - user_datas = RougailUserDataEnvironment( - config, - ).run() + user_datas = RougailUserDataEnvironment(config).run() rougail.user_datas(user_datas) print(config.value.get()) @@ -184,9 +181,7 @@ We can redefine the prefix with `environment.default_environment_name` (prefix i rougail = Rougail() config = rougail.run() - user_datas = RougailUserDataEnvironment( - config, - ).run() + user_datas = RougailUserDataEnvironment(config).run() rougail.user_datas(user_datas) print(config.value.get()) @@ -211,9 +206,7 @@ If you define a `main_namespace` or `extra_namespaces`, the `environment.default rougail = Rougail() config = rougail.run() - user_datas = RougailUserDataEnvironment( - config, - ).run() + user_datas = RougailUserDataEnvironment(config).run() rougail.user_datas(user_datas) print(config.value.get()) @@ -240,9 +233,7 @@ This is why the `environment.with_secrets` parameter allows you to reject secret rougail = Rougail() config = rougail.run() - user_datas = RougailUserDataEnvironment( - config, - ).run() + user_datas = RougailUserDataEnvironment(config).run() rougail.user_datas(user_datas) print(config.value.get()) @@ -300,6 +291,7 @@ Let's execute `script.py` to display help: And now with modified value: .. code-block:: bash + $ python script.py --my_variable "a new value" --no-my_boolean_variable --my_integer_variable 10 --my_secret_variable MyVeryStrongPassword {: 'a new value', : False, : 10, : 'MyVeryStrongPassword'} @@ -338,12 +330,14 @@ You can combine user datas, for example if you want to load datas from environme Let's execute `script.py` with environment variable and commandline arguments: .. code-block:: bash + $ env ROUGAIL_MY_VARIABLE="a new value" ROUGAIL_MY_BOOLEAN_VARIABLE="False" python script.py --my_integer_variable 10 --my_secret_variable MyVeryStrongPassword {: 'a new value', : False, : 10, : 'MyVeryStrongPassword'} If the value of a variable is define with an environment variable and commandline argument, the value is the value of the last user data define: .. code-block:: bash + $ env ROUGAIL_MY_VARIABLE="not a new" python script.py --my_variable "a new value" --no-my_boolean_variable --my_integer_variable 10 --my_secret_variable MyVeryStrongPassword {: 'a new value', : False, : 10, : 'MyVeryStrongPassword'} @@ -373,6 +367,7 @@ Recreate a script with environnement variable support which is display the retur Try to load the value an unknown variable: .. code-block:: bash + $ env ROUGAIL_UNKNOWN_VARIABLE="a value" python script.py {'errors': [], 'warnings': ['variable or family "unknown_variable" does not exist, it will be ignored when loading from environment variable']} @@ -381,13 +376,15 @@ As you can see, a warnings is return. Try to load the value of an hidden variable: .. code-block:: bash + $ env ROUGAIL_MY_HIDDEN_VARIABLE="a value" python script.py {'errors': [], 'warnings': ['variable "my_hidden_variable" (My hidden variable) is hidden, it will be ignored when loading from environment variable']} Finally if a try to change the value of a secret, which is not allowed: .. code-block:: bash + $ env ROUGAIL_MY_SECRET_VARIABLE="MyVeryStrongPassword" python script.py {'errors': ['the variable "my_secret_variable" contains secrets and should not be defined in environment variable'], 'warnings': []} -An error is generate. +An error is generated. diff --git a/docs/structfile.rst b/docs/structfile.rst index cc139e9f0..7cc641ae6 100644 --- a/docs/structfile.rst +++ b/docs/structfile.rst @@ -19,6 +19,11 @@ Definition The header of a structure file ----------------------------------- +A basic structure file is composed of: + +- a YAML 1.2 standard header +- a version attribute + .. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_000/firefox/00-proxy.yml :language: yaml :caption: An empty Rougail structure file. diff --git a/docs/tutorial/index.rst b/docs/tutorial/index.rst index df44d30b1..97f88fe1f 100644 --- a/docs/tutorial/index.rst +++ b/docs/tutorial/index.rst @@ -46,6 +46,11 @@ We'll learn in this tutorial how to set the values of the configuration options It is advisable to follow this tutorial with the help of the corresponding :tutorial:`Rougail git repository tutorial <>`. If you use this rougail tutorial repository, you will have all the necessary files distributed in the correct tree structure. + :: + + git clone https://forge.cloud.silique.fr/stove/rougail-tutorials.git + + Of course, you can also decide to start from scratch and copy/paste the tutorial files content. .. toctree:: diff --git a/docs/tutorial/preliminary.rst b/docs/tutorial/preliminary.rst index 3c81162ae..5cea0a8e2 100644 --- a/docs/tutorial/preliminary.rst +++ b/docs/tutorial/preliminary.rst @@ -5,36 +5,54 @@ Getting started We will learn how to: - - create a Rougail :term:`structure description file ` - - define a Rougail :term:`structure file format version ` - - define a Rougail :term:`variable` and set its :term:`value` + - create a :term:`structure description file ` + - add a :term:`structure file format version ` + - add a :term:`variable` and set its :term:`value` .. prerequisites:: Prerequisites - We assume that Rougail's library is :ref:`installed ` on your computer. - - If you want to follow with this tutorial with the help of the corresponding :tutorial:`Rougail tutorial git repository <>`, - this workshop page corresponds to the tags v1.1_000 to v1.1_004. - -.. of :tutorial:`the Git repository `. + - If you want to follow with this tutorial with the help of the corresponding :tutorial:`Rougail-tutorials git repository <>`, + this workshop page corresponds to the tags :tutorial:`v1.1_000 ` to :tutorial:`v1.1_011 ` + in the repository. -Making a structure file -------------------------- + :: + + git clone https://forge.cloud.silique.fr/stove/rougail-tutorials.git + git switch v1.1_000 + +Creating a structure file +-------------------------- .. demo:: The folder structure Here is the tree structure we want to have:: - workplace - ├── firefox - │   └── struct.yml + rougail-tutorials + └── firefox +    └── 00-proxy.yml -- Let's make a :file:`workplace` directory, with a :file:`firefox` subfolder. -- First, we wil make a :term:`structure file `, so let's create a :file:`struct.yml` file +- Let's make a :file:`rougail-tutorials` directory, with a :file:`firefox` subfolder. +- First, we wil create a :term:`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 structure description file. +.. note:: + + If you don't want to manualy create a file in your favorite text editor + and prefer to start with a ready-made project, you can clone the + :tutorial:`v1.1_000 version of the rougail-tutorials git repository: ` + + :: + + git clone https://forge.cloud.silique.fr/stove/rougail-tutorials.git + git switch v1.1_000 + + Otherwise you can copy/paste this file content: + + +This is an empty Rougail :term:`structure description file: ` .. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_000/firefox/00-proxy.yml :language: yaml @@ -46,20 +64,29 @@ This is an empty Rougail structure description file. version: 1.1 -Let's create our first variable ----------------------------------------------- - -.. type-along:: a first variable - - Let's put a variable in the Rougail :term:`structure description file ` +Let's add our first variable +------------------------------ A variable is defined at a minimum by its name. -This is a first Rougail variable in a Rougail dictionnary: +.. note:: + + If you don't want to manualy create a file in your favorite text editor + and prefer to start with a ready-made project, you can clone the + :tutorial:`v1.1_010 version of the rougail-tutorials git repository: ` + + :: + + git clone https://forge.cloud.silique.fr/stove/rougail-tutorials.git + git switch v1.1_010 + + Otherwise you can copy/paste this file content: + +A :term:`variable` in the :term:`structure description file ` .. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_001/firefox/00-proxy.yml :language: yaml - :caption: A Rougail dictionnary file with only one variable + :caption: A Rougail structure file with only one variable :name: RougailDictionaryFirstVariableName .. @@ -68,7 +95,7 @@ This is a first Rougail variable in a Rougail dictionnary: :download:`download this file ` -- If we run the Rougail CLI utility command +Let's run the Rougail CLI utility command: .. code-block:: text :class: terminal @@ -90,20 +117,23 @@ we will actually have an error: Because this variable is :term:`mandatory` and needs to be set **but** there's no value yet. -We can therefore deduce this result: +We can therefore deduce the fact that: -.. note:: Once defined, an option configuration :term:`value` is :term:`mandatory`. +.. admonition:: Fact + + Once defined, an option configuration :term:`value` is :term:`mandatory`. + That is to say, it is absolutely necessary to assign a value to this variable. Rougail waits for the `proxy_mode` configuration option's value to be set. -.. seealso:: To go further, have a look at the :tiramisu:`mandatory option ` according to the definition of Tiramisu. - .. glossary:: mandatory 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 ` according to the definition of Tiramisu. Let's add a variable's description, which is not mandatory but which is a good practice: