diff --git a/docs/tutorial/images/firefox160.png b/docs/tutorial/images/firefox160.png new file mode 100644 index 000000000..d368003e7 Binary files /dev/null and b/docs/tutorial/images/firefox160.png differ diff --git a/docs/tutorial/images/practice_threevars.png b/docs/tutorial/images/practice_threevars.png new file mode 100644 index 000000000..7d2fb9a5a Binary files /dev/null and b/docs/tutorial/images/practice_threevars.png differ diff --git a/docs/tutorial/practice2.rst b/docs/tutorial/practice2.rst new file mode 100644 index 000000000..af72cdc21 --- /dev/null +++ b/docs/tutorial/practice2.rst @@ -0,0 +1,220 @@ +Practice +================================ + +.. objectives:: Objectives + + Now it's your turn again. + Try making some Rougail. + At the same time, if you get stuck, you have the solutions in the Rougail tutorial + code repository. + + There is nothing new in the three next Firefox variables. So it is the time to practice what we've learned until now. + + This page is divided in two parts for each variable: + + - Explain what we want to implement + - Propose to you a solution + + The best for you is to do this job on your own and compare your work to our propositions. + +Here are the two first variables in the Firefox configuration's widget: + +.. image:: images/practice_threevars.png + +The third appears only if we enable DNS over HTTPS with a custom providers, we have to set a `Custom DNS URL`. + +These three variables are highlighted here in the lower part of the Firefox configuration's widget: + +.. image:: images/firefox160.png + +.. prerequisites:: Prerequisites + + - We assume that Rougail's library is :ref:`installed ` on your computer. + + - It is possible to retrieve the current state of the various Rougail files manipulated in this tutorial step + by checking out the corresponding tag of the `rougail-tutorials` git repository. + Each tag corresponds to a stage of progress in the tutorial. + Of course, you can also decide to copy/paste or download the tutorial files contents while following the tutorial steps. + + If you want to follow this tutorial with the help of the corresponding :tutorial:`rougail-tutorials git repository `, + this workshop page corresponds to the tags :tutorial:`1.1_160 ` to :tutorial:`1.1_162 ` + in the repository. + + :: + + git clone https://forge.cloud.silique.fr/stove/rougail-tutorials.git + git switch --detach 1.1_160 + +A boolean variable +------------------ + +What do we want to be implemented +''''''''''''''''''''''''''''''''''' + +.. exercise:: Exercice + + You need to think about: + + - choose a file name that respect the :ref:`file naming and organizing convention ` + - define an appropriate family and variable name, have a look at our :ref:`variable naming convention ` + - we will set the variable in a family (with others variable later) to separate this purpose + - the family and variable `description` parameter will be the Firefox description + - the variable is a :ref:`boolean ` with the default value `false` (unchecked option) + - the family and variable are always available, it's not directly related to the proxy choice + +Our solution +''''''''''''''''''''''''''''''' + +Please unroll the "Solution" widget to see our solution: + +.. solution:: Solution + + .. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_160/firefox/60-dns_over_https.yml + :language: yaml + :caption: The :file:`firefox/60-dns_over_https.yml` a boolean variable + + - Here we choosed to name the new structure file `firefox/60-dns_over_https.yml`, + the file containing the `dns_over_https` family and the `enable_dns_over_https` variable definition + - this variable is a :ref:`boolean ` with the default value `false` + +.. + %YAML 1.2 + --- + version: 1.1 + + dns_over_https: # DNS over HTTPS + + enable_dns_over_https: false # Enable DNS over HTTPS + ... + +A choice variable +----------------- + +What do we want to be implemented +''''''''''''''''''''''''''''''''''' + +.. exercise:: Exercice + + You need to think about: + + - this variable will be in the same file as the first one + - define an appropriate variable name, have a look at our :ref:`variable naming convention ` + - we will set the variable in the previous family + - the variable `description` parameter will be the Firefox description + - the variable is a :ref:`choice ` with the following proposal: `Cloudflare`, `NextDNS` and `Custom` + - this variable shall be :ref:`disabled ` if the `enable_dns_over_https` variable is `false`. + +Our solution +''''''''''''''''''''''''''''''' + +.. type-along:: For those who follow the tutorial with the help of the git repository + + Now you need to checkout the :tutorial:`v1.1_161 ` version:: + + git switch --detach v1.1_161 + +Please unroll the "Solution" widget to see our solution: + +.. solution:: Solution + + .. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_161/firefox/60-dns_over_https.yml + :language: yaml + :caption: The :file:`firefox/60-dns_over_https.yml` a choice variable + + - Here we choosed to name the new structure file `firefox/60-dns_over_https.yml`, + the file containing the `dns_over_https` family and the `enable_dns_over_https` variable definition + - this variable is false by default + - this variable is :ref:`disabled ` if `enable_dns_over_https` is `false` + +.. + %YAML 1.2 + --- + version: 1.1 + + dns_over_https: # DNS over HTTPS + + enable_dns_over_https: false # Enable DNS over HTTPS + + provider: + description: Use Provider + choices: + - Cloudflare + - NextDNS + - Custom + default: Cloudflare + disabled: + variable: _.enable_dns_over_https + when: false + ... + + +A web_address variable +---------------------- + +What do we want to be implemented +''''''''''''''''''''''''''''''''''' + +.. exercise:: Exercice + + You need to think about: + + - this variable will be in the same file as the two others + - define an appropriate variable name, have a look at our :ref:`variable naming convention ` + - we will set the variable in the previous family + - the variable `description` parameter will be the Firefox description + - the variable is a `web_address` + - this variable shall be :ref:`disabled ` if the `provider` variable is not `Custom` + - the variable `provider` could be :ref:`disabled ` too + + +Our solution +''''''''''''''''''''''''''''''' + +.. type-along:: For those who follow the tutorial with the help of the git repository + + Now you need to checkout the :tutorial:`v1.1_162 ` version:: + + git switch --detach v1.1_162 + +Please unroll the "Solution" widget to see our solution: + +.. solution:: Solution + + .. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_162/firefox/60-dns_over_https.yml + :language: yaml + :caption: The :file:`firefox/60-dns_over_https.yml` a choice variable + + - Here we choosed to name the new structure file `firefox/60-dns_over_https.yml`, + the file containing the `custom_dns_url` variable definition + - this is a :ref:`web_address ` variable + - this variable is :ref:`disabled ` if `provider` has :ref:`an access property error ` and `provider` has not the value "Custom" + +.. + %YAML 1.2 + --- + version: 1.1 + + dns_over_https: # DNS over HTTPS + + enable_dns_over_https: false # Enable DNS over HTTPS + + provider: + description: Use Provider + choices: + - Cloudflare + - NextDNS + - Custom + default: Cloudflare + disabled: + variable: _.enable_dns_over_https + when: false + + custom_dns_url: + description: Custom DNS URL + type: web_address + disabled: + jinja: |- + {{ _.provider is propertyerror or _.provider != 'Custom' }} + return_type: boolean + description: if "_.provider" is not "Custom" + ...