diff --git a/docs/tutorial/examples.rst b/docs/tutorial/examples.rst index 3067909c7..bfc5b5eb9 100644 --- a/docs/tutorial/examples.rst +++ b/docs/tutorial/examples.rst @@ -33,7 +33,8 @@ A full documented variable Examples ----------- -All you need to do is add an `examples` parameter to the structural definition of our variable. +How to define example usage? All you need to do is add an `examples` parameter to the structural definition of your variable. +Let's give some usage examples of how to use our `no_proxy` variable: .. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_120/firefox/40-no_proxy.yml @@ -64,6 +65,53 @@ All you need to do is add an `examples` parameter to the structural definition o when: No proxy ... +.. attention:: Note: the `examples` parameter does not specify default values. **It's just examples, it's not a setting**. + +Here we can see that there are no default values set and as our variable is not :term:`mandatory`, +if we don't set values in the user data files as the `no_proxy` variable is :term:`multi`, the `no_proxy` value will be the empty list `[]`: + +.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_120/config/03/config.yml + :language: yaml + :caption: The :file:`config/03/config.yml` user data file with an `example` parameter but no value set + +.. + --- + proxy_mode: Automatic proxy configuration URL + auto: https://auto.proxy.net/wpad.dat + no_proxy: + - example.net + - 192.168.1.0/24 + + +.. raw:: html + :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_120/config/03/cmd_ro.txt + :class: terminal + +.. + rougail -m firefox/ --types types/proxy -u yaml -yf config/01/config.yml + +.. raw:: html + :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_120/config/03/output_ro.html + :class: output + +.. + ╭────────────── Caption ───────────────╮ + │ Variable Default value │ + │ Modified value │ + │ (⏳ Original default value) │ + ╰──────────────────────────────────────╯ + Variables: + ┣━━ 📓 Configure Proxy Access to the Internet: Automatic proxy configuration URL ◀ loaded from the YAML file "config/03/config.yml" + ┃ (⏳ No proxy) + ┣━━ 📓 Automatic proxy configuration URL: https://auto.proxy.net/wpad.dat ◀ loaded from the YAML file "config/03/config.yml" + ┗━━ 📓 Address for which proxy will be desactivated: [] + +.. type-along:: If we set some user data values + +.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_120/config/02/config.yml + :language: yaml + :caption: The :file:`config/03/config.yml` user data file with some value set + .. raw:: html :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_120/config/02/cmd_ro.txt :class: terminal @@ -71,8 +119,6 @@ All you need to do is add an `examples` parameter to the structural definition o .. rougail -m firefox/ --types types/proxy -u yaml -yf config/02/config.yml - - .. raw:: html :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_120/config/02/output_ro.html :class: output @@ -91,4 +137,5 @@ All you need to do is add an `examples` parameter to the structural definition o ┣━━ example.net ◀ loaded from the YAML file "config/02/config.yml" ┗━━ 192.168.1.0/24 ◀ loaded from the YAML file "config/02/config.yml" +.. note:: In all cases, we can see that none of the values ​​cited in the examples (`.mozilla.org`, `.net.nz`) appear. diff --git a/docs/tutorial/multiple.rst b/docs/tutorial/multiple.rst index bab863ac1..06646be09 100644 --- a/docs/tutorial/multiple.rst +++ b/docs/tutorial/multiple.rst @@ -284,6 +284,9 @@ Now we have this output: A multi is a multiple variable, that is a variable that can have multiple values. +.. note:: Note that the value of a :term:`multi` variable which has no default value set and which is not :term:`mandatory` + will be the empty list `[]` + .. keypoints:: Key points We have now some kind of a container facility named `multi`, that can be applied